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Preface 


This manual provides users of the VMS operating system with an overview of 
the capabilities and functions of the VMS Run-Time Library. 

Run-Time Library routines can only be used in programs written in languages 
that produce native code for the VAX hardware. At present, these languages 
include VAX MACRO and the following compiled high-level languages: 


VAX Ada 
VAX BASIC 
VAX BLISS-32 
VAX C 
VAX COBOL 
VAX COBOL-74 
VAX CORAL 
VAX DIBOL 
VAX FORTRAN 
VAX Pascal 
VAX PL/I 
VAX RPG 
VAX SCAN 


Interpreted languages that can also access Run-Time Library routines include 
VAX DSM and DATATRIEVE. 


Intended Audience 

This manual is intended for system and application programmers who want 
to call Run-Time Library routines. 


Document Structure 

This manual is organized into three chapters as follows: 

• Chapter 1 gives an overview of the VMS Run-Time Library. 

• Chapter 2 discusses the documentation format used in the reference 
section of the various Run-Time Library facility manuals. 

• Chapter 3 discusses the calling formats used to call Run-Time Library 
routines. 


ix 








Preface 


Associated Documents 

The Run-Time Library Routines are documented in a series of reference 
manuals. This manual provides an overview of the Run-Time Library and a 
description of how to access its routines. Descriptions of the individual Run¬ 
Time Library facilities, along with reference sections describing the individual 
routines in detail, can be found in the following books: 

• The VMS RTL DECtalk (DTK$) Manual 

• The VMS RTL Library (LIB$) Manual 

• The VMS RTL Mathematics (MTH$) Manual 

• The VMS RTL General Purpose (OTS$) Manual 

• The VMS RTL Parallel Processing (PPL$) Manual 

• The VMS RTL Screen Management (SMG$) Manual 

• The VMS RTL String Manipulation (STR$) Manual 

The VAX Procedure Calling and Condition Handling Standard, which is 
documented in the Introduction to VMS System Routines, contains useful 
information for anyone who wants to call Run-Time Library routines. 

Applications programmers in any language may wish to refer to the Guide to 
Creating VMS Modular Procedures for the Modular Programming Standard and 
other guidelines. 

VAX MACRO programmers will find additional information on calling Run¬ 
Time Library routines in the VAX MACRO and Instruction Set Reference 
Manual. 

High-level language programmers will find additional information on calling 
Run-Time Library routines in the language reference manual. Additional 
information may also be found in the language user's guide provided with 
your VAX language documentation. 

The Guide to Using VMS Command Procedures may also be useful. 

For a complete list and description of the manuals in the VMS document set, 
see the Overview of VMS Documentation. 
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Conventions 


Convention 

Meaning 

|ret| 

In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

CTRL/C 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

$ SHOW TIME 

05-JUN-1988 11:55:22 

In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) is shown in red. 

$ TYPE MYFILE.DAT 

In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 

input-file, . . . 

In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 

[logical-name] 

Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 














Introduction 


The VMS Common Run-Time Procedure Library (or simply the Run-Time 
Library) is a library of prewritten, commonly-used routines that perform a 
wide variety of operations. These Run-Time Library routines follow the VAX 
Procedure Calling and Condition Handling Standard and the VMS Modular 
Programming Standard; hence they are part of the Common Run-Time 
environment. The Common Run-Time environment lets a program contain 
routines written in different languages, so that you can call Run-Time Library 
routines from any VAX language, thus increasing program flexibility. 

In this manual, a routine is a closed, ordered set of instructions that performs 
one or more specific tasks. Every routine has an entry point (the routine 
name), and optionally an argument list. Procedures and functions are specific 
types of routines: a procedure is a routine that does not return a value, 
whereas a function is a routine that returns a value by assigning that value to 
the function's identifier. 


Organization of the Run-Time Library 

The routines of the VMS Run-Time Library are grouped according to the 
types of tasks they perform; these groups are referred to as facilities. Each 
group or facility has an associated prefix that is used in the routine name 
to identify that routine as a member of a particular facility. Table 1-1 lists 
all the Run-Time Library facility prefixes and the types of tasks each facility 
performs. 


1-1 








Introduction 
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Table 1-1 Run-Time Library Facilities 


Facility Prefix 

Types of Tasks Performed 

DTK$ 

DECtalk routines that are used to control DIGITAL's 
DECtalk device 

LIBS 

Library routines that obtain records from devices, 
manipulate strings, convert data types for I/O, 
allocate resources, obtain system information, signal 
exceptions, establish condition handlers, enable 
detection of hardware exceptions, and process 
cross-reference data 

MTH$ 

Mathematics routines that perform arithmetic, 
algebraic, and trigonometric calculations 

OTS$ 

General purpose routines that perform tasks such 
as data type conversions as part of a compiler's 
generated code, and also some mathematical 
functions 

PPL$ 

Parallel processing routines that simplify subprocess 
creation, interprocess communication, and resource 
sharing for parallel applications 

SMGS 

Screen management routines that are used in 
designing, composing, and keeping track of complex 
images on a video screen 

STR$ 

String manipulation routines that perform such tasks 
as searching for substrings, concatenating strings, 
and prefixing and appending strings 


The following tables list all the routines available for each of the 
aforementioned facilities, as well as a brief statement of the routine's 
function. Table 1-2 lists all the DTK$ facility routines that are used to 
operate DIGITAL's DECtalk device. For more detailed information on these 
routines, or on the DTK$ facility in general, refer to the VMS RTL DECtalk 
(DTK$) Manual. 

Table 1—2 DTK$ Facility Routines 


Routine Name 

Function 

DTK$ANSWER_PHONE 

Wait for the phone to ring and 
answer 


DTK$CHECK_HDWR_STATUS Check the hardware status 


DTK$DIAI_PHONE 

DTK$HANGUP_PHONE 

DTK$INITIALIZE 

DTK$LOAD_DICTIONARY 

Dial the telephone 

Hang up the phone 

Initialize the DECtalk device 

Load a word into the DECtalk 
dictionary 

DTK$READ_KEYSTROKE 

Read a key entered on the phone 
keypad 
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Table 1-2 (Cont.) DTK$ Facility Routines 


Routine Name 

Function 

DTK$READ_STRING 

Read a series of keys entered on the 
phone keypad 

DTK$RETURN_LAST—INDEX 

DTK$SET_INDEX 

DTK$SET_KEYP AD-MODE 
DTK$SET_LOGGING_MODE 

Return the last index spoken 

Insert an index at the current position 
Turn the phone keypad on and off 

Set the specified logging mode on 
the DECtalk terminal 

DTKSSET—MODE 

Set the specified mode on the 
DECtalk terminal 

DTK$SET_SPEECH_MODE 

DTKSSET—TERMINAI_MODE 

Turn the speech on and off 

Set the specified terminal mode on 
the DECtalk terminal 

DTKSSET—VOICE 

DTKSSPEAK—FILE 

DTKSSPEAK—PHONEMIC—TEXT 

DTKSSPEAK—TEXT 

DTKSSPELI_TEXT 

DETERMINATE 

Set the voice characteristics 

Speak text from the specified file 
Speak the specified phonemic text 
Speak the specified text 

Spell out the specified text 

Terminate the DECtalk device 


Table 1-3 lists all of the LIBS facility routines. For more detailed information 
on these routines, or on the LIBS facility in general, refer to the VMS RTL 
Library (LIB$) Manual. 

Table 1-3 LI B$ Facility Routines 


Routine Name 

Function 

LIBSADAWI 

LIB$ADD_TIMES 

LIBSADDX 

Add adjacent word with interlock 

Add two quadword times 

Add two multiple-precision binary 
numbers 

LIB$ANALYZE_SDESC 

LIBSASN—WTH—MBX 

LIBS AST-IN -PROG 

LIBSATTACH 

LIBSBBCCI 

LIBSBBSSI 

LIBSCALLG 

Analyze a string descriptor 

Assign a channel to a mailbox 

AST in progress 

Attach a terminal to a process 

Test and clear a bit with interlock 

Test and set a bit with interlock 

Call a procedure with a general 
argument list 

LIBSCHAR 

Transform a byte to the first 
character of a string 

LIBSCONVERT—DATE—STRING 

Convert a date string to a quadword 
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Table 1—3 (Cont.) LIBS Facility Routines 

Routine Name Function 


LIB$CRC 

LIB$CRC_TABLE 

LIB$CREATE_DIR 

LIB$CREATE_USER_VM_ZONE 

LIB$CREATE_VM_ZONE 

LIB$CRF_INS_KEY 


Calculate a Cyclic Redundancy Check 
(CRC) 

Construct a Cyclic Redundancy 
Check (CRC) table 

Create a directory 

Create a user-defined storage zone 

Create a new storage zone 

Insert a key in the cross-reference 
table 


LIB$CRF_INS_REF 

LIB$CRF_OUTPUT 

LIB$CURRENCY 

LIB$CVT_DX_DX 

LIB$CVT_FROM_INTERNAI_TIME 

LIB$CVTF_FROM_INTERNAI_TIME 

LIB$CVT_TO_INTERNAI_TIME 

LIB$CVTF_TO—INTERN Al_TIME 

LIB$CVT_xTB 

LIB$CVT_VECTIM 

LIB$DATE_TIME 

LIBSDAY 

LIB$DAY_OF_WEEK 

LIB$DECODE_FAULT 


Insert a reference to a key in the 
cross-reference table 

Output some cross-reference table 
information 

Get the system currency symbol 
Convert the specified data type 
Convert internal time to external time 

Convert internal time to external time 
(F-floating value) 

Convert external time to internal time 

Convert external time to internal time 
(F-floating value) 

Convert numeric text to binary 

Convert 7-word vector to internal 
time 

Return the date and time as a string 

Return the day number as a 
longword integer 

Return the numeric day of the week 

Decode instruction stream during a 
fault 


LIB$DEC_OVER 

LIB$DELETE_FILE 

LIB$DELETE_LOGICAL 

LIB$DELETE_SYMBOL 

LIB$DELETE_VM_ZONE 

LIB$DIGIT_SEP 

LIB$DISABLE_CTRL 

LIB$DO_COMMAND 

LIB$EDIV 


Enable or disable decimal overflow 
detection 

Delete one or more files 
Delete a logical name 
Delete a CLI symbol 
Delete a virtual memory zone 
Get the digit separator symbol 

Disable CLI interception of control 
characters 

Execute the specified command 
Perform an extended-precision divide 
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Table 1-3 ICont.) LIB$ Facility Routines 


Routine Name 

LIB$EMODF 

LIB$EMODD 

LIBSEMODG 

LIB$EMODH 

LIB$EMUL 

LIB$ENABLE_CTRL 

LIBSESTABLISH 

LIB$EXTV 

LIB$EXTZV 

LIB$FFx 

LIB$FID_TO_NAME 

LIB$FILE_SCAN 

LIB$FILE_SCAN_END 

LIB$FIND_FILE 

LIB$FIND_FILE_END 

LIB$FIND_IMAGE_SYMBOL 

LIB$FIND_VM_ZONE 

LIB$FIXUP_FLT 

LIB$FLT_UNDER 

LIB$FORMAT_D ATE-TIME 

LIB$FREE_DATE_TIME—CONTEXT 

LIB$FREE_EF 
LIB$FREE_LUN 
LIB$FREE_TIMER 
LIB$FREE_VM 

LIB$FREE_VM—PAGE 

LIB$GETDVI 

LIB$GETJPI 

LIB$GETQUI 

LIB$GETSYI 

LIB$GET_COMMAND 


Function_ 

Perform extended multiply and 

integerize for F-floating values 

Perform extended multiply and 
integerize for D-floating values 

Perform extended multiply and 
integerize for G-floating values 

Perform extended multiply and 
integerize for H-floating values 

Perform an extended-precision 
multiply 

Enable CLI interception of control 
characters 

Establish a condition handler 
Extract a field and sign-extend 
Extract a zero-extended field 
Find the first clear or set bit 

Convert a device and file ID to a file 
specification 

Perform a file scan 
End of file scan 
Find a file 
End of find file 

Merge activate an image symbol 
Find the next valid zone 
Fix floating reserved operand 
Floating-point underflow detection 
Format a date and/or time 

Free the context used to format a 
date or time 

Free an event flag 
Free a logical unit number 
Free timer storage 

Free virtual memory from the 
program region 

Free a virtual memory page 
Get device/volume information 
Get job/process information 
Get queue information 
Get systemwide information 
Get line from SYS$COMMAND 


1-5 






Introduction 

1.1 Organization of the Run-Time Library 


Table 1—3 (Cont.) LIBS Facility Routines 
Routine Name Function 


LIB$GET COMMON 

LIB$GET_DATE_FORMAT 

LIB$GET_EF 

LIB$GET_FOREIGN 

LIB$GET_INPUT 

LIB$GET_LUN 

LIB$GET_MAXIMUM_DATE_LENGTH 

LIB$GET_SYMBOL 

LIB$GET_USERS_LANGUAGE 

LIB$GET_VM 

LIB$GET_VM_PAGE 

LIB$ICHAR 

LIB$INDEX 

LIB$INIT_DATE_TIME_CONTEXT 

LIB$INIT_TIMER 

LIB$INSERT_TREE 

LIB$INSQHI 

LIB$INSQTI 

LIBSINSV 

LIB$INT_OVER 

LIBSLEN 

LIBSLOCC 

LIB$LOOKUP_KEY 

LIB$LOOKUP_TREE 

LIB$LP_LINES 

LIB$MATCHC 

LIB$MATCH_COND 

LIBSM0VC3 

LIB$MOVC5 

LIB$MOVTC 

LIBSMOVTUC 

LIB$MULT_DELTA_TIME 


Get string from common area 

Return the user's date input format 

Get an event flag 

Get foreign command line 

Get line from SYS$INPUT 

Get logical unit number 

Get the maximum possible date/time 
string length 

Get the value of a CLI symbol 
Return the user's language choice 
Allocate virtual memory 
Get a virtual memory page 

Convert first character of string to 
integer 

Index to relative position of substring 

Initialize the context used in 
formatting date/time strings 

Initialize times and counts 
Insert entry in a balanced binary tree 
Insert entry at the head of a queue 
Insert entry at the tail of a queue 
Insert a variable bit field 
Integer overflow detection 

Return the length of a string as a 
longword 

Locate a character 

Look up keyword in table 

Look up an entry in a balanced binary 
tree 

Specify the number of lines on each 
printer page 

Match characters, return relative 
position 

Match condition values 
Move characters 
Move characters with fill 
Move translated characters 
Move translated until character 
Multiply delta time by scalar 
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Table 1-3 (Cont.) LIBS Facility Routines 


Routine Name 

Function 

LIB$MULTF_DELTA_TIME 

Multiply delta time by F-floating 
scalar 

LIB$PAUSE 

LIB$POLYF 

Pause program execution 

Evaluate polynomials for F-floating 
values 

LIB$POLYD 

Evaluate polynomials for D-floating 
values 

LIBSPOLYG 

Evaluate polynomials for G-floating 
values 

LIBSPOLYH 

Evaluate polynomials for H-floating 
values 

LIB$PUT_COMMON 

LIB$PUT_OUTPUT 

LIB$RADIX-POINT 

LIBSREMQHI 

LIBSREMQTI 

LIB$RENAME_FILE 

LIB$RESERVE_EF 

LIB$RESET_VM_ZONE 

LIBSREVERT 

Put string into common area 

Put line to SYSSOUTPUT 

Radix point symbol 

Remove entry from head of queue 
Remove entry from tail of queue 
Rename one or more files 

Reserve an event flag 

Reset virtual memory zone 

Revert to the handler of the 
procedure activator 

LIBSRUN-PROGRAM 

LIB$SCANC 

Run new program 

Scan for characters and return 
relative position 

LIB$SCOPY_DXDX 

Copy source string by descriptor to 
destination 

LIB$SCOPY_R_DX 

Copy source string by reference to 
destination 

LIB$SET_LOGICAL 

LIB$SET_SYMBOL 

LIB$SFREE1_DD 

LIB$SFREEN_DD 

LIB$SGET1_DD 

LIBSSHOW-TIMER 

LIB$SHOW_VM 

LIB$SHOW_VM_ZONE 

Set logical name 

Set value of a CLI symbol 

Free one or more dynamic strings 
Free n dynamic strings 

Get one dynamic string 

Show accumulated times and counts 

Show virtual memory statistics 

Display information about a virtual 
memory zone 

LIBSSIGNAL 

LIBSSIG—TO_RET 

Signal exception condition 

Convert signaled message to a return 
status 
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Table 1—3 (Cont.) LIBS Facility Routines 


Routine Name 

Function 

LIB$SIG TO STOP 

Convert a signaled condition to a 
signaled stop 

LIB$SIM_TRAP 

Simulate floating trap 

LIBSSKPC 

Skip equal characters 

LIBSSPANC 

Skip selected characters 

LIBSSPAWN 

Spawn a subprocess 

LIBSST AT—TIMER 

Return accumulated time and count 
statistics 

LIB$STAT_VM 

Return virtual memory statistics 

LIBSSTOP 

Stop execution and signal the 
condition 

LIB$SUB_TIMES 

Subtract two quadword times 

LIBSSUBX 

Perform multiple-precision binary 
subtraction 

LIB$SYS_ASCTIM 

Invoke $ASCTIM to convert binary 
time to ASCII 

LIB$SYS_FAO 

Invoke $FAO system service to 
format output 

LIB$SYS_FAOL 

Invoke $FAOL system service to 
format output 

LIB$SYS_GETMSG 

Invoke $GETMSG system service to 
get message text 

LIBSTPARSE 

Implement a table-driven, finite-state 
parser 

LIB$TRA_ASC_EBC 

Translate ASCII to EBCDIC 

LIB$TRA_EBC_ASC 

Translate EBCDIC to ASCII 

LIBSTRA VERSE_TREE 

Traverse a balanced binary tree 

LIB$TRIM_FILESPEC 

Fit long file specification into fixed 
field 

LIBSVERIFY—VM_ZONE 

Verify a virtual memory zone 

LIBSWAIT 

Wait a specified period of time 


Table 1-4 lists all of the MTH$ facility routines. For more detailed 
information on these routines, or on the MTH$ facility in general, refer to 
the VMS RTL Mathematics (MTH$) Manual. 
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Table 1-4 MTH$ Facility Routines 


Routine Name 

Function 

MTH$xACOS 

MTHSxACOSD 

MTH$xASIN 

MTH$xASIND 

MTH$xATAN 

MTHSxATAND 

MTH$x AT AN2 

MTH$xATAND2 

MTH$xATANH 

MTHSCxABS 

MTH$CCOS 

MTHSCxCOS 

MTH$CEXPP 

MTHSCxEXP 

Return arc cosine of angle expressed in radians 1 

Return arc cosine of angle expressed in degrees 1 

Return arc sine in radians 1 

Return arc sine in degrees 1 

Return arc tangent in radians 1 

Return arc tangent in degrees 1 

Return arc tangent in radians with two arguments 1 

Return arc tangent in degrees with two arguments 1 

Return hyperbolic arc tangent 1 

Return complex absolute value 2 

Return complex cosine (F-floating complex value) 

Return complex cosine (D- and G-floating complex values) 
Return complex exponential (F-floating complex value) 

Return complex exponential (D- and G-floating complex 
values) 

MTH$CLOG 

MTH$CxLOG 

Return complex natural logarithm (F-floating complex value) 

Return complex natural logarithm (D- and G-floating 
complex values) 

MTH$CMPLX 

MTH$xCMPLX 

MTHSCONJG 

Return complex number made from F-floating point values 
Return complex number made from D- and G-floating values 

Return conjugate of a complex number (F-floating point 
complex value) 

MTH$xCONJG 

Return conjugate of a complex number (D- and G-floating 
complex values) 

MTH$xCOS 

MTHSxCOSD 

MTH$xCOSH 

MTHSCSIN 

Return cosine of angle expressed in radians 1 

Return cosine of angle expressed in degrees 1 

Return hyperbolic cosine 1 

Return complex sine of complex number (F-floating complex 
value) 

MTHSCxSIN 

Return complex sine of complex number (D- and G-floating 
complex values) 

MTH$CSQRT 

MTH$CxSQRT 

Return complex square root (F-floating point value) 

Return complex square root (D- and G-floating complex 
values) 

MTH$CVT_x_x 

Convert one double-precision value 


MTH$CVT_xA _xA Convert an array of double-precision values 

MTH$xEXP Return an exponential 1 


’The routine is valid only for the F-, D-, and G-floating point data types. The corresponding 
H-floating routine is listed separately with the format MTH$Hrouf»ne_name. 

2 The routine is valid for the three floating-point complex data types: F-, D- and G-floating 
point complex. 
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1.1 Organization of the Run-Time Library 


Table 1—4 (Cont.) MTH$ Facility Routines 


Routine Name 

Function 

MTH$HACOS 

MTH$HACOSD 

MTH$HASIN 

MTH$HASIND 

MTHSHATAN 

MTH$HATAND 

MTH$HATAN2 

Return arc cosine in radians (H-floating point value) 

Return arc cosine in degrees (H-floating point value) 

Return arc sine in radians (H-floating point value) 

Return arc sine in degrees (H-floating point value) 

Return arc tangent in radians (H-floating point value) 

Return arc tangent in degrees (H-floating point value) 

Return arc tangent in radians (H-floating point) with two 
arguments 

MTHSHATAND2 

Return arc tangent in degrees (H-floating point) with two 
arguments 

MTH$HATANH 

MTHSHCOS 

Return hyperbolic arc tangent (H-floating point value) 

Return cosine of angle expressed in radians (H-floating 
point value) 

MTH$HCOSD 

Return cosine of angle expressed in degrees (H-floating 
point value) 

MTH$HCOSH 

MTHSHEXP 

MTH$HLOG 

MTH$HLOG2 

MTH$HLOG10 

MTHSHSIN 

Return hyperbolic cosine (H-floating point value) 

Return exponential (H-floating point value) 

Return natural logarithm (H-floating point value) 

Return base two logarithm (H-floating point value) 

Return common logarithm (H-floating point value) 

Return sine of angle expressed in radians (H-floating point 
value) 

MTH$HSIND 

Return sine of angle expressed in degrees (H-floating point 
value) 

MTH$HSINH 

MTH$HSQRT 

MTH$HT AN 

Return hyperbolic sine (H-floating point value) 

Return square root (H-floating point value) 

Return tangent of angle expressed in radians (H-floating 
point value) 

MTH$HTAND 

Return tangent of angle expressed in degrees (H-floating 
point value) 

MTH$HTANH 

MTH$xlMAG 

MTHSxLOG 

MTH$xLOG2 

MTH$xL0G10 

MTH$RANDOM 

MTHSxREAL 

Compute the hyperbolic tangent (H-floating point value) 
Return imaginary part of a complex number 2 

Return the natural logarithm 1 

Return base two logarithm 1 

Return common logarithm 1 

Generate a random number with uniform distribution 

Return real part of a complex number 2 


lThe routine is valid only for the F-, D-, and G-floating point data types. The corresponding 
H-floating routine is listed separately with the format MTH$H routine-name. 

2 The routine is valid for the three floating-point complex data types: F-, D- and G-floating 
point complex. 
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Introduction 

1.1 Organization of the Run-Time Library 


Table 1-4 (Cont.) 

MTH$ Facility Routines 

Routine Name 

Function 

MTHSxSIN 

MTHSxSINCOS 

MTH$xSINCOSD 

MTH$xSIND 

MTHSxSINH 

MTH$xSQRT 

MTH$xT AN 

MTH$xTAND 

MTH$xTANH 

MTHSUMAX 

MTH$UMIN 

Return sine of angle expressed in radians 1 

Return sine and cosine of angle expressed in radians 3 

Return sine and cosine of angle expressed in degrees 3 

Return sine of angle expressed in degrees 1 

Return hyperbolic sine 1 

Return square root 1 

Return tangent of angle expressed in radians 1 

Return tangent of angle expressed in degrees 1 

Compute the hyperbolic tangent 1 

Compute the unsigned maximum 

Compute the unsigned minimum 


’The routine is valid only for the F-, D-, and G-floating point data types. The corresponding 
H-floating routine is listed separately with the format MTH$Hrouf/ne_name. 

3 The routine is valid for the four floating-point data types: F-, D-, G-, and H-floating. 


Table 1-5 lists all of the OTS$ facility routines. For more detailed information 
on these routines, or on the OTS$ facility in general, refer to the VMS RTl 
General Purpose (OTS$) Manual. 

Table 1-5 OTS$ Facility Routines 


Routine Name 

Function 

OTS$CNVOUT 

Convert D-floating, G-floating, or H-floating to 
character string 

OTS$CVT_l_TB 

OTS$CVT_l_Tl 

OTS$CVT_l—TL 

OTS$CVT_l_TO 

OTS$CVT_l_TU 

OTS$CVT_l_TZ 

OTS$CVT_TB_L 

OTS$CVT_TI_L 

OTS$CVT_TI—L 

OTS$CVT_TO_L 

OTS$CVT_TU_L 

OTS$CVT_T_z 

OTS$CVT_T_x 

OTS$CVT_TZ_L 

OTSSDIVCx 

Convert unsigned integer to binary text 

Convert signed integer to signed integer text 
Convert integer to logical text 

Convert unsigned integer to octal text 

Convert unsigned integer to decimal text 

Convert integer to hexadecimal text 

Convert binary text to unsigned integer 

Convert signed integer text to integer 

Convert logical text to integer 

Convert octal text to integer 

Convert unsigned decimal text to integer 

Convert numeric text to D- or F-floating value 
Convert numeric text to G- or H-floating value 
Convert hexadecimal text to unsigned longword 
Perform complex division 
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1.1 Organization of the Run-Time Library 


Table 1—5 (Cont.) OTS$ Facility Routines 


Routine Name 

Function 

OTS$DIV PK LONG 

OTS$DIV_PK_SHORT 

OTS$MOVE3 

OTSSMOVE5 

OTSSMULCx 

OTSSPOWCxCx 

Perform packed decimal division with long divisor 
Perform packed decimal division with short divisor 
Move data without fill 

Move data with fill 

Perform complex multiplication 

Raise a complex base to a complex floating-point 
exponent 

OTS$POWCxJ 

Raise a complex base to a signed longword 
exponent 

OTS$POWDD 

OTSSPOWDR 

OTSSPOWDJ 

OTS$POWGx 

Raise a D-floating base to a D-floating exponent 

Raise a D-floating base to an F-floating exponent 

Raise a D-floating base to a longword exponent 

Raise a G-floating base to a G-floating or longword 
exponent 

OTSSPOWGJ 

OTSSPOWHx 

OTSSPOWHJ 

OTS$POWII 

OTS$POWHJJ 

OTS$POWLULU 

Raise a G-floating base to a longword exponent 

Raise an H-floating base to floating-point exponent 

Raise an H-floating base to a longword exponent 

Raise a word base to a word exponent 

Raise a longword base to a longword exponent 

Raise an unsigned longword base to an unsigned 
longword exponent 

OTSSPOWxLU 

Raise a floating-point base to an unsigned 
longword exponent 

OTSSPOWRD 

OTSSPOWRR 

OTSSPOWRJ 

OTS$SCOPY_DXDX 

Raise an F-floating base to a D-floating exponent 

Raise an F-floating base to an F-floating exponent 

Raise an F-floating base to a longword exponent 

Copy a source string passed by descriptor to a 
destination string 

OTS$SCOPY_R_DX 

Copy a source string passed by reference to a 
destination string 

OTS$SFREE 1 _DD 

OTS$SFREEN_DD 

OTSSSGET1_DD 

Free one dynamic string 

Free n dynamic strings 

Get one dynamic string 


Table 1-6 lists all of the PPL$ facility routines. These routines are used 
to implement parallel processing applications on VMS systems. For more 
detailed information on these routines, or on the PPL$ facility in general, 
refer to the VMS RTL Parallel Processing (PPL$) Manual. 


1-12 









Introduction 

1.1 Organization of the Run-Time Library 


Table 1 -6 PPL$ Facility Routines 

Routine Name Function 


PPL$ ADJUST-QUORUM 
PPL$AWAIT_EVENT 
PPLSCREATE—BARRIER 
PPLSCRE ATE -EVENT 
PPLSCREATE—SEMAPHORE 
PPLSCREATE _SHARED_MEMORY 
PPLSCREATE—SPIN—LOCK 
PPLSCREATE _VM -ZONE 
PPLSDECREMENT—SEMAPHORE 

PPLSDELETE—SHARED—MEMORY 
PPLSENABLE—EVENT—AST 
PPLSENABLE—EVENT—SIGNAL 
PPLSFIND—SYNCH—ELEMENT—ID 
PPLSFLUSH—SHARED—MEMORY 
PPLSGET—INDEX 
PPLSINCREMENT—SEMAPHORE 

PPLSINDEX—TO_PID 
PPLSINITIALIZE 
PPLSPID—TO_INDEX 
PPLSRELE ASE —SPIN —LOCK 
PPLSREAD—SEMAPHORE 

PPLSSEIZE—SPIN—LOCK 
PPLSSET—QUORUM 
PPLSSPAWN 
PPLSSTOP 
PPLSTERMINATE 
PPLSTRIGGER—EVENT 
PPLSUNIQUE —NAME 
PPLSWAIT—AT BARRIER 


Adjust the barrier quorum 

Await the occurrence of an event 

Create a barrier 

Create an event 

Create a semaphore 

Create shared memory 

Create a spin lock 

Create a new virtual memory zone 

Decrement a semaphore to gain access to 
a resource 

Delete shared memory 

Enable AST notification of an event 

Enable signal notification of an event 

Find the synchronization element identifier 

Flush shared memory 

Get the index of a participant 

Increment a semaphore to release a 
resource 

Convert a participant-index to a VMS PID 
Initialize the PPL$ facility 
Convert a VMS PID to a participant-index 
Release a spin lock 

Read the values associated with a 
particular semaphore 

Seize a spin lock 
Set the barrier quorum 
Initiate parallel execution 
Stop a participant 
Terminate PPL$ participation 
Trigger an event 
Provide a unique name 
Synchronize at a barrier 


Table 1-7 lists all of the SMG$ facility routines. These routines are used 
to perform screen management operations. For more detailed information 
on these routines, or on the SMG$ facility in general, refer to the VMS RTL 
Screen Management (SMG$) Manual. 
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1.1 Organization of the Run-Time Library 


Table 1—7 SMG$ Facility Routines 

Routine Name Function 


SMG$ADD_KEY_DEF 

SMG$BEGIN_DISPLAY_UPDATE 

SMG$BEGIN_PASTEBOARD_UPDATE 

SMGSCANCEL-INPUT 
SMG$CHANGE_PBD_CHARACTERISTICS 
SMG$CHANGE—RENDITION 
SMG$CHANGE_VIEWPORT 

SMG$CHANGE_VIRTUAI_DISPLAY 

SMG$CHECK_FOR_OCCLUSION 
SMGSCONTROL -MODE 
SMG$COPY_VIRTUAL-DISPLAY 
SMGSCRE ATE _KEY_TABLE 
SMG$CREATE_MENU 
SMG$CREATE_PASTEBOARD 
SMGSCRE ATE—SUBPROCESS 
SMGSCREATE—VIEWPORT 

SMGSCREATE—VIRTUAI_DISPLAY 

SMGSCREATE—VIRTUAI_KEYBOARD 

SMGSCURSOR—COLUMN 
SMGSCURSOR—ROW 
SMGSDEFINE—KEY 

SMGSDEI_TERM—T ABLE 

SMGSDELETE—CHARS 
SMGSDELETE—KEY—DEF 
SMGSDELETE—LINE 
SMGSDELETE—MENU 
SMGSDELETE—PASTEBOARD 
SMGSDELETE -SUBPROCESS 
SMGSDELETE—VIEWPORT 
SMGSDELETE—VIRTUAL -DISPLAY 

SMGSDELETE—VIRTUAI_KEYBOARD 

SMGSDIS ABLE -BROADCAST-TRAPPING 

SMGSDISABLE—UNSOLICITED—INPUT 

SMGSDRAW—CHAR 
SMGSDRAW—LINE 


Add a key definition 

Begin batching of display updates 

Begin batching of pasteboard 
updates 

Cancel input request 

Change pasteboard characteristics 

Change default rendition 

Change a viewport associated with a 
virtual display 

Change a virtual display 

Check for occlusion 

Control mode 

Copy a virtual display 

Create a key table 

Create a menu in a virtual display 

Create a pasteboard 

Create and initialize a subprocess 

Create a virtual viewport 

Create a virtual display 

Create a virtual keyboard 

Return the cursor column position 

Return the cursor row position 

Perform a DEFINE/KEY command 

Delete a terminal table 

Delete the specified characters 

Delete a key definition 

Delete a line 

Delete a menu 

Delete a pasteboard 

Terminate a subprocess 

Delete a viewport 

Delete a virtual display 

Delete a virtual keyboard 

Disable the trapping of broadcast 
messages 

Disable the trapping of unsolicited 
input 

Draw the specified character 
Draw a line 
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1.1 Organization of the Run-Time Library 


Table 1-7 (Cont.) SMG$ Facility Routines 


Routine Name 
SMG$DRAW_RECT ANGLE 
SMG$ENABLE_UNSOLICITED_INPUT 

SMG$END_DISPLAY_UPDATE 

SMG$END_PASTEBOARD_UPDATE 

SMG$ERASE_CHARS 

SMG$ERASE_COLUMN 

SMG$ERASE_DISPLAY 

SMG$ERASE_LINE 

SMG$ERASE_PASTEBOARD 

SMG$EXECUTE_COMMAND 

SMG$FIND_CURSOR_DISPLAY 

SMG$FLUSH_BUFFER 

SMG$GET_BROADCAST_MESSAGE 

SMG$GET_CHAR_AT_PHYSICAI— 
CURSOR 

SMG$GET_DISPLAY_ATTR 
SMG$GET_KEY_DEF 
SMG$GET_KEYBOARD_ATTRIBUTES 
SMG$GET_NUMERIC_DAT A 
SMG$GET_PASTEBOARD_ATTRIBUTES 
SMG$GET_PASTING_INFO 
SMG$GET_TERM_DAT A 
SMG$GET_VIEWPORT_CHAR 

SMG$HOME_CURSOR 
SMG$INIT_TERM_T ABLE 
SMG$INIT_TERM—TABLE _BY_TYPE 

SMG$INSERT_CHARS 
SMG$INSERT_LINE 
SMG$INVALIDATE—DISPLAY 
SMG$KEYCODE_TO—NAME 
SMGSLABEL-BORDER 
SMG$LIST_KEY—DEFS 
SMGSLIST—PASTING—ORDER 
SMG$LOAD_KEY—DEFS 


Function 

Draw a rectangle 

Enable the trapping of unsolicited 
input 

End the batching of display updates 

End the batching of pasteboard 
updates 

Erase the specified characters 
Erase a column from the display 
Erase a virtual display 
Erase a line from the display 
Erase a pasteboard 

Execute the specified command in a 
subprocess 

Find the virtual display that contains 
the cursor 

Flush the buffer 

Get the broadcast message 

Return the character at the cursor 

Get the display attributes 

Get the key definition 

Get the keyboard attributes 

Get the numeric data 

Get the pasteboard attributes 

Get the display pasting information 

Get the terminal data 

Get the characteristics of the display 
viewport 

Home the cursor 
Initialize the terminal table 

Initialize TERMTABLE by VMS 
terminal type 

Insert the specified characters 
Insert a line 

Mark a virtual display as invalid 
Translate a key code to a key name 
Label a virtual display border 
List key definitions 
List the display pasting order 
Load key definitions 
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1.1 Organization of the Run-Time Library 


Table 1-7 (Cont.) SMG$ Facility Routines 


Routine Name 

SMG$LOAD_VIRTUAI_DISPLAY 

SMG$MOVE_TEXT 
SMG$MOVE_VIRTUAL—DISPLAY 
SMG$NAME_TO_KEYCODE 

SMG$PASTE_VIRTUAI_DISPLAY 

SMG$POP_VIRTUAL-DISPLAY 
SMG$PRINT_PASTEBOARD 

SMG$PUT_CHARS 
SMG$PUT_CHARS—HIGHWIDE 


Function 

Load a virtual display from a file 

Move the specified text 

Move a virtual display 

Translate a key name to a key code 

Paste a virtual display 

Delete a series of virtual displays 

Print the pasteboard using a print 
queue 

Write characters to a virtual display 

Write double-height, double-width 
characters 


SMG$PUT_CHARS—MULTI Put text with multiple renditions to 

the display 


SMG$PUT_CHARS—WIDE 
SMG$PUT_HELP—TEXT 
SMG$PUT_LINE 
SMG$PUT_LINE—HIGHWIDE 


Write wide characters 

Output HELP text to a display 

Write lines to a virtual display 

Write double-height, double-width 
line 


SMG$PUT_LINE—MULTI 

SMGSPUT—LINE—WIDE 
SMG$PUT_PASTEBOARD 
SMG$PUT_ST ATUS—LINE 

SMG$READ_COMPOSED—LINE 
SMG$READ_FROM—DISPLAY 
SMG$READ_KEYSTROKE 
SMG$READ_STRING 
SMG$READ_VERIFY 
SMG$REMOVE_LINE 
SMG$REPAINT_LINE 


Put text with multiple renditions to a 
display in line mode 

Write a double-width line 

Output pasteboard via routine 

Output a line of text to the hardware 
status line 

Read a composed line 

Read text from a display 

Read a single character 

Read a string 

Read and verify a string 

Remove a line from a virtual display 

Repaint one line on the current 
screen 


SMG$REPAINT_SCREEN 

SMG$REPASTE_VIRTUAI_DISPLAY 

SMG$REPLACE_INPUT—LINE 
SMG$RESTORE_PHYSICAL-SCREEN 
SMGSRETURN—CURSOR—POS 
SMG$RETURN_INPUT—LINE 
SMG$RING_BELL 
SMGSSAVE—PHYSICAL—SCREEN 


Repaint the current screen 
Repaste the virtual display 
Replace the input line 
Restore the physical screen 
Return the cursor position 
Return the input line 
Ring the terminal bell or buzzer 
Save the physical screen 
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1.1 Organization of the Run-Time Library 


Table 1-7 (Cont.) SMG$ Facility Routines 


Routine Name 

Function 

SMG$SAVE_VIRTUAI_DISPLAY 

SMG$SCROLL _DISPLA Y_ARE A 

SMG$SCROLL —VIEWPORT 

SMG$SELECT_FROM_MENU 

SMG$SET_BROADCAST_TRAPPING 

Save the virtual display to a file 

Scroll the display area 

Scroll a display under a viewport 

Select an item from a menu 

Enable the trapping of broadcast 
messages 

SMG$SET_CURSOR_ABS 

SMG$SET_CURSOR_MODE 

SMG$SET_CURSOR_REL 

Set absolute cursor position 

Turn the physical cursor on or off 

Set the cursor relative to the current 
position 

SMG$SET_DEF AULT_ST ATE 
SMG$SET_DISPL AY_SCROLL -REGION 

SMG$SET_KEYPAD—MODE 

SMG$SET_OUT—OF_BAND—ASTS 

Set the default state 

Create a display scrolling region 

Set the keypad mode 

Establish an AST routine for out-of- 
band characters 

SMG$SET_PHYSICAL -CURSOR 
SMG$SET_TERM-CHARACTERISTICS 

SMGSSNAPSHOT 

SMGSUNPASTE—VIRTUAL -DISPLAY 

Set the cursor on the physical screen 
Change the terminal characteristics 
Write a snapshot of the pasteboard 
Remove the specified virtual display 


Table 1-8 lists all of the STR$ facility routines. These routines are used to 
perform string manipulation operations. For more detailed information on 
these routines, or on the STR$ facility in general, refer to the VMS RTL String 
Manipulation (STR$) Manual. 

Table 1 -8 STR$ Facility Routines 


Routine Name 

Function 

STR$ADD 

STR$ANALYZE_SDESC 

STRSAPPEND 

STR$CASE_BLIND—COMPARE 

STRSCOMPARE 

STRSCOMP ARE _EQL 

STR$COMPARE_MULTI 

Add two decimal strings 

Analyze a string descriptor 

Append a string 

Compare strings without regard to case 
Compare two strings 

Compare two strings for equality 

Compare two strings for equality using 
the DEC Multinational Character Set 

STRSCONCAT 

STR$COPY_DX 

Concatenate two or more strings 

Copy a source string passed by 
descriptor to a destination string 

STRSCOPY—R 

Copy a source string passed by reference 
to a destination string 
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1.1 Organization of the Run-Time Library 


Table 1—8 (Cont.) STR$ Facility Routines 


Routine Name 

Function 

STRSDIVIDE 

Divide two decimal strings 

STRSDUPI_CHAR 

Duplicate character n times 

STRSELEMENT 

Extract delimited element substring 

STR$FIND_FIRST_IN_SET 

Find the first character in a set of 
characters 

STR$FIND_FIRST_NOT_IN_SET 

Find the first character that does not 
occur in the set 

STR$FIND_FIRST_SUBSTRING 

Find the first substring in the input string 

STR$FREE1_DX 

Free one dynamic string 

STR$GET1_DX 

Allocate one dynamic string 

STR$LEFT 

Extract a substring of a string 

STR$LEN_EXTR 

Extract a substring of a string 

STR$MATCH_WILD 

Match a wildcard specification 

STR$MUL 

Multiply two decimal strings 

STR$POSITION 

Return relative position of a substring 

STR$POS_EXTR 

Extract a substring of a string 

STR$PREFIX 

Prefix a string 

STR$RECIP 

Return the reciprocal of a decimal string 

STRSREPLACE 

Replace a substring 

STR$RIGHT 

Extract a substring of a string 

STR$ROUND 

Round or truncate a decimal string 

STRSTRANSLATE 

Translate matched characters 

STR$TRIM 

Trim trailing blanks and tabs 

STR$UPCASE 

Convert string to all uppercase 


1.2 Features of the Run-Time Library 

The Run-Time Library provides the following features and capabilities: 

• Run-Time Library routines perform a wide range of general utility 
operations. You can call a Run-Time Library routine from any VAX 
language instead of writing your own code to perform the operation. 

Routines in the Run-Time Library are part of the VAX Common Run¬ 
Time environment; therefore, they can be called from any VAX language. 
Because they follow the VMS Modular Programming Standard, Run-Time 
Library routines can be easily incorporated into any program. 

• Because many of the routines are shared, they take up less space in 
memory. 

• When new versions of the Run-Time Library are installed, you do not 
need to revise your calling program, and generally do not need to relink. 
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1.2 Features of the Run-Time Library 


• All Run-Time Library routines are fully reentrant unless the description of 
the facility or the routine specifies otherwise. 

The term reentrant means that the routine executes correctly regardless of 
how many threads of execution are executing at the same time. Currently, 
reentrancy is supported only when those multiple threads are executing 
on the same processor. The term AST-reentrant means that a routine 
may be interrupted and reentered from itself or an AST-level thread of 
execution only. In particular, an AST-reentrant routine may not execute 
properly if more than one non-AST-level thread of execution is executing 
the routine at once. 

Because the Run-Time Library routines are reentrant (unless otherwise 
noted), they can be called from multiple threads of execution. For 
example, a routine may be called from both an AST-level thread and 
a non-AST-level thread of an image, as well as from the multiple tasks of 
an Ada program. 


1.3 Linking with the Run-Time Library 

Routines in the Run-Time Library execute entirely in the mode of the caller 
and are intended to be called in user mode. This section explains how to link 
your program and the Run-Time Library into a single executable unit. 

When you link your program, the VMS Linker creates an executable image. 

If your program includes explicit or implicit calls to the Run-Time Library, 
the linker automatically searches the following system libraries for the named 
procedures: 

• The system default shareable image library, IMAGELIB.OLB 

The most frequently used portions of the Run-Time Library are contained 
in this set of shareable images. When you link your program, the linker 
searches IMAGELIB.OLB to resolve undefined symbols. That is, your 
program is linked by default with the shareable images in this library to 
form an executable image. 

• The system default object module library, STARLET.OLB 

A portion of the Run-Time Library is contained as object modules in 
STARLET.OLB. If the linker does not find the shareable image of the 
routine in IMAGELIB.OLB, it copies the object module of the routine from 
STARLET.OLB into your program's executable image. 

Note that when your program calls a routine that is part of a shareable image, 
the linker does not copy the routine into your program's executable image, as 
it does for routines maintained in the object module library. 

Using shareable images offers the following advantages: 

• Many programs can use the single copy of a shareable image, so each 
program takes up less space in physical memory and less disk storage. 

• More than one program can use a shareable image simultaneously, thus 
saving memory space. 

• When new versions of the Run-Time Library are installed, you do not 
need to relink the programs that call the shareable Run-Time Library. 
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2 


Run-Time Library Documentation Format 


Each Run-Time Library routine is documented using a structured format 
called the routine template. This section discusses the main headings in the 
routine template, the information that is presented under each heading, and 
the format used to present the information. 

The purpose of this section, therefore, is to explain where to find information 
and how to read it correctly — not how to use the routines themselves. For 
information on using Run-Time Library routines, see Chapter 3. 

Some main headings in the routine template contain information that requires 
no further explanation beyond what is given in Table 2-1. However, the 
following main headings contain information that does require additional 
discussion, and this discussion takes place in the remaining subsections of 


this section. 

• Format heading 

• Returns heading 

• Arguments heading 

• Condition Values Returned heading 

Table 2-1 Main Headings in the Routine Template 

Main Heading 

Description 

Routine name 

Required. The routine entry point name appears at the 
top of the first page. It is usually, though not always, 
followed by the English name of the routine. 

Routine overview 

Required. The routine overview appears directly below 
the routine name. The overview explains, usually in 
one or two sentences, what the routine does. 

Format 

Required. The format heading follows the routine 
overview. The format gives the routine entry point 
name and the routine argument list. It also specifies 
whether arguments are required or optional. 

Returns 

Required. The returns heading follows the routine 
format. It explains what information is returned by the 
routine. 

Arguments 

Required. The arguments heading follows the returns 
heading. Detailed information about each argument is 
provided under the arguments heading. If a routine 
takes no arguments, the word “None” appears. 
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Run-Time Library Documentation Format 


Table 2—1 (Cont.) Main Headings in the Routine Template 


Main Heading 

Description 

Description 

Optional. The description heading follows the 
arguments heading. The description section contains 
more detailed information about specific actions taken 
by the routine: interaction between routine arguments, 
if any; operation of the routine within the context of 
VMS; user privileges needed to call the routine, if any; 
system resources used by the routine; and user quotas 
that may affect the operation of the routine. 


Note that any restrictions on the use of the routine 
are always discussed first in the description section; 
for example, any required user privileges or necessary 
system resources are explained first. 

Condition Values 
Returned 

Required. The condition values returned section 
appears following the description section. It lists the 
condition values (typically status or completion codes) 
that are returned by the routine. 

Example 

Optional. The examples heading appears following 
the condition values returned heading. The example 
section contains one or more programming examples 
to illustrate use of the routine. Text explaining the 
example is most often provided. 


2.1 Format Heading 

Under the format heading, the following three types of information can be 
present. 

• Procedure call format 

• Jump to Subroutine (JSB) format 

• Explanatory text 

All Run-Time Library routines have a procedure call format, but not all Run¬ 
Time Library routines have JSB formats; in fact, most do not. If a routine has 
a JSB format, it always appears after the routine's procedure call format. 

By using the procedure call format, your routine call conforms to the VAX 
Procedure Calling and Condition Handling Standard. That is, an entry mask 
is created, registers are saved, and so on. 

Use of the JSB call format results in activation of the routine code directly, 
without the overhead of constructing the entry mask, saving registers, and so 
on. The JSB call format can be used only by VAX MACRO and VAX BLISS 
programs. 

Explanatory text may appear following one or both of the above formats. 
This text is present only when needed to clarify the formats. 

A procedure call format appears under the format heading as follows: 

ENTRY_POINT_NAME argl ,arg2 ,[arg3] ,nullarg [,arg4] [,arg5] 
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The preceding format shows the use of the following syntax rules. 

• Entry point names 

Entry point names are always shown in uppercase characters. 

• Argument names 

Argument names are always shown in lowercase characters. 

• Spaces 

One or more spaces are used between the entry point name and the first 
argument, and between each argument and the next. 

• Brackets ([]) 

Brackets surround optional arguments; in the previous example, arg3, 
arg4, and arg5 are optional arguments because they are surrounded by 
brackets. 

• Commas 

Between arguments, the comma always follows the space. That is, 
the comma immediately precedes an argument instead of immediately 
following the previous one. If the argument is optional, the comma may 
appear inside or outside the brackets. If the optional argument is not the 
last argument in the list, you must either pass a zero by value or use the 
comma as a place holder to indicate the place of the omitted argument. 

If the optional argument is the last argument in the list, you must still 
include the comma if the comma appears outside the brackets; if the 
comma appears inside the brackets you can omit the argument entirely. 

For example, arg3 in the previous example is an optional argument; 
but because there are other required arguments that follow arg3 in the 
list, the comma itself is not optional (since it marks the place of arg3); 
therefore, the comma is not inside the brackets. 

The arguments arg4 and arg5 are optional. Because there are no required 
arguments that follow arg4 and arg5 in the list, the commas in front of 
arg4 and arg5 are themselves optional; that is, the commas would not be 
specified in the call if arg4 and arg5 were not specified. Therefore, the 
commas in front of arg4 and arg5 are inside the brackets. Note however 
that if arg5 is specified, the comma in front of arg4 is required whether or 
not arg4 is specified. 

• Null arguments 

A null argument is a place-holding argument. It is used for either of the 
following two reasons: (1) to hold a place in the argument list for an 
argument that has not yet been implemented by DIGITAL but which 
may be at some future time or (2) to mark the position of an argument 
that was used in earlier versions of the routine but which is not used 
in the latest version (upward compatibility is thereby ensured because 
arguments that follow the null argument in the argument list keep their 
original positions). 

In the argument list constructed when a procedure is called, both null 
arguments and omitted optional arguments are represented by longword 
argument list entries containing the value 0. The programming language 
syntax required to produce argument list entries containing 0 differs from 
language to language, so you should refer to your language user's guide 
for language-specific syntax. 
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However, in general, the following rule applies to high-level languages: 
to mark a null argument or to omit an optional argument in the call, 
specify a comma (,) for each null argument or omitted optional argument. 


2.2 


2 . 2.1 


Returns Heading 

Under the returns heading appears a description of what information, if any, 
is returned by the routine to the caller. A routine can return information 
to the caller in various ways. The subsections that follow discuss each 
possibility and then describe how this returned information is presented 
under the returns heading. 


Condition Values in RO 

Most Run-Time Library routines return a condition value in register RO. This 
condition value contains various kinds of information, but most importantly 
for the caller, it describes (in bits 0 through 3) the completion status of the 
operation. Programmers test the condition value to determine if the routine 
completed successfully, or to determine the cause of the error. 

For the purposes of high-level language programmers, the fact that status 
information is returned by means of a condition value and that it is returned 
in a VAX register is of little importance because the high-level language 
programmer receives this status information in the return (or status) variable 
he or she uses when making the call. The Common Run-Time environment 
established for high-level languages allows the status information in RO to be 
moved automatically to the user's return variable. 


Nevertheless, if a routine returns a condition value in RO, the returns heading 
in the documentation will contain the following information: 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


• The "VMS Usage" heading specifies how the data type is interpreted. 
VMS Usages are discussed in detail further in this chapter. 

• The "type" heading specifies the data type of the information returned. 
Since the data type of a condition value is an unsigned longword, the 
"type" heading shows "longword (unsigned)". 

• The "access" heading specifies the way in which the called routine 
accesses the object. Since the called routine is returning the condition 
value, it is writing into this longword; so the "access" heading shows 
"write only". 

• The "mechanism" heading specifies the passing mechanism used by the 
called routine in returning the condition value. Since the called routine 
is writing the condition value directly into RO, the mechanism heading 
shows "by value". (If the called routine had written the address of the 
condition value into RO, the passing mechanism would have been "by 
reference".) 
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Note that if a routine returns a condition value in RO, another main heading 
in the routine template (Condition Values Returned) describes the possible 
condition values that the routine can return. This heading is discussed further 
in this chapter. 


2.2.2 Data in Registers RO Through R11 

Some routines return actual data in the VAX registers. The number of 
registers needed to contain the data depends on the length (or data type) 
of the information being returned. For example, a Run-Time Library 
mathematics routine that is returning the cosine of an angle as a G-floating 
number would use registers RO and R1 because the length of a G-floating 
number is two longwords. 

If a routine returns actual data in one or more of the registers RO through 
Rll, the returns heading in the documentation of that routine will contain the 
following information: 

VMS Usage: yyyyyyyy 

type: xxxxxxxx 

access: write only 

mechanism: by value 

The symbol "yyyyyyyy" indicates the VMS usage of the information. In this 
particular case, the VMS usage would be floating-point. 

The symbol "xxxxxxxx" above indicates the data type of the information being 
returned. For example, for the mathematics routine discussed above, the data 
type would be G-floating. 

Additionally, some explanatory text may be provided following the 
information about the usage, type, access, and mechanism of the returned 
value. This text explains other relevant information about what the routine is 
returning. 

It is important to note that, since the routine is returning actual data in the 
VAX registers, the registers cannot be used to convey completion status 
information. All routines that return actual data in VAX registers must signal 
a condition value that contains the completion status. If this is the case, the 
heading reads "Condition Values Signaled". This heading is discussed further 
in this chapter. 


2.3 Arguments Heading 

Under the arguments heading appears detailed information about each 
argument listed in the call format. Arguments are described in the order in 
which they appear in the call format. If the routine has no arguments, the 
term "none" appears. 

The following format is used to describe each argument. 
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argument-name 

VMS Usage: 
type: 
access: 
mechanism: 


VMS-usage-type 

argument-data-type 

argument-access 

argument-passing-mechanism 


Additionally, the arguments heading contains at least one paragraph of 
structured text, followed by other paragraphs of text, as needed. 

The following sections discuss each part of the arguments heading separately. 


2.3.1 VMS Usage Entry 

The VMS usage entry indicates the abstract data structure of the argument. 
Table 2-2 contains a list of the VMS data structures. Note that most high- 
level language documentation sets contain a table listing all the VMS usages 
and the statements required to implement each usage in the appropriate 
language. 

Table 2-2 VMS Data Structures 

Data Structure Definition 


access_bit_names Homogeneous array of 32 quadword 

descriptors; each descriptor defines the 
name of one of the 32 bits in an access mask. 
The first descriptor names bit 0, the second 
descriptor names bit 1 and so on. 

access_mode Unsigned byte denoting a hardware access 

mode. This unsigned byte can take four 
values: 0 specifies kernel mode; 1, executive 
mode; 2, supervisor mode; and 3, user mode. 

address Unsigned longword denoting the virtual 

memory address of either data or code, 
but not of a procedure entry mask (which is of 
type “procedure"). 

address_range Unsigned quadword denoting a range of virtual 

addresses, which identify an area of memory. 
The first longword specifies the beginning 
address in the range; the second longword 
specifies the ending address in the range. 

arg—list Procedure argument list consisting of one 

or more longwords. The first longword 
contains an unsigned integer count of the 
number of successive, contiguous longwords, 
each of which is an argument to be passed 
to a procedure by means of a VAX CALL 
instruction. 

The argument list has the following format: 
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Table 2-2 (Cont.) VMS Data Structures 
Data Structure Definition 



ast_procedure 

boolean 

byte_signed 

byte_unsigned 

channel 

char_string 


Unsigned longword integer denoting the entry 
mask to a procedure to be called at AST level. 
(Procedures that are not to be called at AST 
level are of type “procedure".) 

Unsigned longword denoting a Boolean truth 
value flag. This longword may have only two 
values: 1 (true) and 0 (false). 

This VMS data type is the same as the data 
type “byte (signed)“in Table 2-3. 

This VMS data type is the same as the data 
type “byte integer (unsigned)" in Table 2-3. 

Unsigned word integer that is an index to an 
I/O channel. 

String of from 0 to 65,535 8-bit characters. 
This VMS data type is the same as the data 
type "character string" in Table 2-3. The 
following diagram pictures the character string 
“XYZ“. 

7 0 


“X” 

: A 

: A+1 

: A+2 

«Y» 


ZK-4202-85 


complex_number One of the VAX standard complex floating¬ 

point data types. The three complex floating¬ 
point numbers are: F-floating complex, 
D-floating complex, and G-floating complex. 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure Definition 


An F-floating complex number (r,i) is 
composed of two F-floating point numbers. 
The first F-floating point number is the real 
part (r) of the complex number; the second 
F-floating point number is the imaginary part 
(i). The structure of an F-floating complex 
number is as follows: 


15 14 7 6 0 


REAL 

PART 

IMAGINARY 

PART 


s 

EXPONENT 

FRACTION 


FRACTION 

s 

EXPONENT 

FRACTION 


FRACTION 


: A 

: A+2 
: A+6 
: A+8 


ZK-4203-85 


A D-floating complex number (r,i) is 
composed of two D-floating point numbers. 
The first D-floating point number is the real 
part (r) of the complex number; the second 
D-floating point number is the imaginary part 
(i). The structure of a D-floating complex 
number is as follows: 

15 14 7 6 0 

: A 

: A+2 
: A+4 
: A+6 
: A8 
: A+10 
: A+12 
: A+14 

ZK-4201-85 


REAL 

PART 


IMAGINARY 
PART 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


A G-floating complex number (r,i) is 
composed of two G-floating point numbers. 
The first G-floating point number is the real 
part (r) of the complex number; the second 
G-floating point number is the imaginary part 
(i). The structure of a G-floating complex 
number is as follows: 
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REAL 

PART 


IMAGINARY 

PART 


15 14 43 0 


t 

s 

EXPONENT 

FRACTION 

FRACTION 

FRACTION 

FRACTION 

s 

EXPONENT 

FRACTION 

FRACTION 

FRACTION 

FRACTION 


: A 

: A+2 
: A+4 
: A+6 
:A8 
: A+10 
: A+12 
: A+14 
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cond_value Unsigned longword integer denoting a 

condition value (that is, a return status or 
system condition code), which is typically 
returned by a procedure in RO. The structure 
of a condition value is as follows: 


31 28 27 


3 2 0 


cntrl 



facility number 


message number 


ZK-1795-84 

context Unsigned longword that is used by a called 

procedure to maintain position over an iterative 
sequence of calls. It is usually initialized by the 
caller, but thereafter manipulated by the called 
procedure. 

date_time 64-bit unsigned, binary integer denoting a 

date and time as the number of elapsed 
100-nanosecond units since 00:00 o'clock, 
November 17, 1858. This VMS data type is 
the same as the data type "absolute date and 
time" in Table 2-3. 
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Table 2-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 


device_name 

Character string denoting the 1 - to 9-character 
name of a device. It can be a logical name, but 
if it is, it must translate to a valid device name. 
If the device name contains a colon (:), the 
colon and the characters past it are ignored. 
When an underscore (_) precedes the device 
name string, it indicates that the string is a 


physical device name. 


ef_cluster_name 

Character string denoting the 1- to 15- 
character name of an event flag cluster. It 
can be a logical name, but if it is, it must 
translate to a valid event flag cluster name. 

For more information on how the system 
translates logical names to global section 
names see the “Event Flag Services" section 
of the Introduction to VMS System Services. 

ef_number 

Unsigned longword integer denoting the 


number of an event flag. 

Local event flags 


numbered 32 to 63 are available to your 


programs. 


exit_handler_block 

Variable-length structure denoting an exit 
handler control block. This control block, 
which describes the exit handler, is depicted in 


the following diagram. 


31 


0 

forward link (used by VMS only) 

exit handler address 

these 3 bytes must be 0 

arg. count 

address of condition value (written by VMS) 


additional arguments for the 
exit handler; these are optional; 
one argument per longword 

_ 


ZK-1714-84 


fab Structure denoting an RMS file access block. 

A complete description of this structure is 
contained in the VMS Record Management 
Services Manual. 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure_Definition_ 

file-protection Unsigned word that is a 16-bit mask that 

specifies file protection. The mask contains 
four 4-bit fields, each of which specifies the 
protection to be applied to file access attempts 
by one of the four categories of user: from 
the rightmost field to the leftmost field, (1) 
system users, (2) the file owner, (3) users in 
the same UIC group as the owner, and (4) all 
other users (the world). Each field specifies, 
from the rightmost bit to the leftmost bit: (1) 
delete access, (2) execute access, (3) write 
access, (4) read access. Set bits indicate that 
access is denied. 

The following diagram depicts the 16-bit 
file-protection mask. 


WORLD 

GROUP 
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E 
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floating_point 


One of the VAX standard floating-point data 
types. These types are F_floating, D_floating, 
G-floating, and H-floating. 

The structure of an F-floating number is as 
follows: 

15 14 76 0 

: A 

: A+2 


-4197-85 

The structure of a D-floating number is as 
follows: 


S 

EXPONENT 

FRACTION 

FRACTION 


31 16 


ZK 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure Definition 

15 14 76 0 

A 

A+2 
A+4 
A+6 


ZK-4198-85 

The structure of a G-floating number is as 
follows: 

15 14 43 0 

: A 

: A+2 
: A+4 
: A+6 

63 48 

ZK-4199-85 

The structure of an H-floating number is as 
follows: 

15 14 0 

A 

A+2 
A+4 
A+6 
A+8 
A+10 
A+12 
A+14 

127 113 

ZK-4196-85 


EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 



S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


63 


48 
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Table 2-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 

function—code 

Unsigned longword specifying the exact 
operations a procedure is to perform. This 
longword has two word-length fields: the 
first field is a number specifying the major 
operation; the second field is a mask or bit 
vector specifying various suboperations within 
the major operation. 

io_status—block 

Quadword structure containing information 
returned by a procedure that completes 
asychronously. The information returned 
varies depending on the procedure. The 
following figure illustrates the format of the 
information written in the IOSB. 

31 

16 

15 0 

count 

condition value 

device-dependent information 


ZK-856-82 

The first word contains a condition value 
indicating the success or failure of the 
operation. The condition values used are 
the same as for all returns from system 
services; for example, SS$_NORMAL indicates 
successful completion. 

The second word contains the number of 
bytes actually transferred in the I/O operation. 
Note that for some devices this word contains 
only the low-order word of the count. For 
information on specific devices, see the VMS 
I/O User's Reference Volume. 

The second longword contains device¬ 
dependent return information. 

To ensure successful I/O completion and the 
integrity of data transfers, the IOSB should be 
checked following I/O requests, particularly for 
device-dependent I/O functions. For complete 
details on how to use the I/O status block, 
see the VMS I/O User's Reference Volume. 

item _list_2 Structure that consists of one or more 

item descriptors and that is terminated by 
a longword containing 0. Each item descriptor 
is a 2-longword structure that contains three 
fields. The following diagram depicts a single 
item descriptor. 
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Data Structure 

Definition 


31 

15 

0 

item code 

component length 

component address 


ZK-1709-84 


The first field is a word in which the service 
writes the length (in characters) of the 
requested component. If the service does 
not locate the component, it returns the value 
0 in this field and in the component address 
field. 

The second field contains a user-supplied, 
word-length symbolic code that specifies 
the component desired. The item codes are 
defined by the macros that are specific to the 
service. 


The third field is a longword in which the 
service writes the starting address of the 
component. This address is within the input 
string itself. 

item_list_3 Structure that consists of one or more 

item descriptors and that is terminated by 
a longword containing 0. Each item descriptor 
is a 3-longword structure that contains four 
fields. The following diagram depicts the 
format of a single item descriptor. 


31 


15 


item code 


buffer length 


buffer address 


return length address 


ZK-1705-84 

The first field is a word containing a user- 
supplied integer specifying the length (in bytes) 
of the buffer in which the service writes the 
information. The length of the buffer needed 
depends upon the item code specified in the 
item code field of the item descriptor. If the 
value of buffer length is too small, the service 
truncates the data. 
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Table 2-2 (Cont.) 

VMS Data Structures 

Data Structure 

Definition 

item_quota_list 

The second field is a word containing a user- 
supplied symbolic code specifying the item of 
information that the service is to return. These 
codes are defined by macros that are specific 
to the service. 

The third field is a longword containing the 
user-supplied address of the buffer in which 
the service writes the information. 

The fourth field is a longword containing the 
user-supplied address of a word in which 
the service writes the length in bytes of the 
information it actually returned. 

Structure that consists of one or more quota 
descriptors and that is terminated by a byte 
containing a value defined by the symbolic 
name PQL$_LISTEND. Each quota descriptor 
consists of a 1 -byte quota name followed by 
an unsigned longword containing the value for 
that quota. 

lock_id 

Unsigned longword integer denoting a lock 
identifier. This lock identifier is assigned by 
the lock manager facility to a lock when the 
lock is granted. 

lock_status_block 

Structure into which the lock manager facility 
writes status information about a lock. A 
lock status block always contains at least two 
long words: the first word of the first longword 
contains a condition value; the second word 
of the first longword is reserved to DIGITAL; 
and the second longword contains the lock 
identifier. 

The lock status block receives the final 
condition value and the lock identification, and 
optionally contains a lock value block. When 
a request is queued, the lock identification is 
stored in the lock status block even if the lock 
has not been granted. This allows a procedure 
to dequeue locks that have not been granted. 

The condition value is placed in the lock status 
block only when the lock is granted (or when 
errors occur in granting the lock). 

The following diagram depicts a lock status 
block that includes the optional 16-byte lock 
value block. 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure Definition 


reserved 

condition value 

lock identification 


16-byte lock value block 
(used only when LCK$M_VALBLK is set) 


ZK-376-81 


lock_value_block 


logical_name 


longword_signed 

longword_unsigned 

mask_byte 


mask_longword 


mask_quadword 


mask_word 


16-byte block that the lock manager facility 
includes in a lock status block if the user 
requests it. The contents of the lock value 
block are user defined and are not interpreted 
by the lock manager facility. 

Character string of from 1 to 255 characters 
that identifies a logical name or equivalence 
name to be manipulated by VMS logical name 
system services. Logical names that denote 
specific VMS objects have their own VMS 
types: for example, a logical name identifying 
a device has the VMS type "device_name". 

This VMS data type is the same as the data 
type "longword integer (signed)" in Table 2-3. 

This VMS data type is the same as the data 
type "longword (unsigned)" in Table 2-3. 

Unsigned byte wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of "flags" or as a "bit 
mask". 

Unsigned longword wherein each bit is 
interpreted by the called procedure. A mask is 
also referred to as a set of "flags" or as a "bit 
mask". 

Unsigned quadword wherein each bit is 
interpreted by the called procedure. A mask is 
also referred to as a set of "flags" or as a "bit 
mask". 

Unsigned word wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of "flags" or as a "bit 
mask". 
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Table 2-2 (Cont.) 

VMS Data Structures 

Data Structure 

Definition 

null_arg 

Unsigned longword denoting a "null argument." 
A "null argument" is an argument whose only 
purpose is to hold a place in the argument list. 

octaword_signed 

This VMS data type is the same as the data 
type "octaword integer (signed)" in Table 2-3. 

octaword_unsigned 

This VMS data type is the same as the data 
type "octaword (unsigned)" in Table 2-3. 

page-protection 

Unsigned longword specifying page protection 
to be applied by the VAX hardware. 

Protection values are specified using bits 0 
to 3; bits 4 to 31 are ignored. 

The $PRTDEF macro defines the following 
symbolic names for the protection codes: 

Symbol Description 

PRT$C_NA No access 

PRT$C_KR Kernel read only 

PRT$C_KW Kernel write 

PRT$C_ER Executive read only 

PRT$C_EW Executive write 

PRT$C_SR Supervisor read only 

PRT$C_SW Supervisor write 

PRT$C_UR User read only 

PRT$C_UW User write 

PRT$C_ERKW Executive read; kernel 

write 

PRT$C_SRKW Supervisor read; kernel 

write 

PRT$C_SREW Supervisor read; executive 

write 

PRT$C_URKW User read; kernel write 

PRT$C_UREW User read; executive write 

PRT$C_URSW User read; supervisor write 

procedure 

If the protection is specified as 0, -the 
protection defaults to kernel read-only. 

Unsigned longword denoting the entry mask 
to a procedure that is not to be called at AST 
level. (Arguments specifying procedures to 
be called at AST level have the VMS type 
"ast—procedure".) 
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Table 2-2 (Cont.) VMS Data Structures 


Data Structure 


Definition 


process_id 


process_name 

quadword_signed 

quadword_unsigned 

rights_holder 


Unsigned longword integer denoting a process 
identifier (PID). This process identifier is 
assigned by VMS to a process when the 
process is created. 

Character string, containing 1 to 15 characters, 
that specifies the name of a process. 

This VMS data type is the same as the data 
type "quadword integer (signed)" Table 2-3. 

This VMS data type is the same as the data 
type "quadword (unsigned)" in Table 2-3. 

Unsigned quadword specifying a user's access 
rights to a system object. This quadword 
consists of two fields: the first is an unsigned 

longword identifier (VMS type "rights_id") and 

the second is a longword bitmask wherein 
each bit specifies an access right. 

Once the identifier record exists in the rights 
database, you define the holders of that 
identifier with the $ADD_HOLDER system 
service. You pass the binary identifier value 
with the id argument; you specify the holder 
with the holder argument, which is the 
address of a quadword data structure with 
the following format. 


UIC identifier of holder 


0 


ZK-1903-84 


One holder record exists in the rights database 
for each holder of each identifier. The holder 
record associates the holder with the identifier, 
specifies the attributes of the holder, and 
identifies the UIC identifier of the holder. The 
format of a holder record is as follows: 


identifier value 


attributes 


UIC identifier of holder 


(reserved) 


ZK-1907-84 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure Definition 

The rights database is an indexed file with 
three keys. The primary key is the identifier 
value, the secondary key is the holder ID, and 
the third key is the identifier name. Through 
the use of the secondary key of the holder 
ID, all the rights held by a process can be 
retrieved quickly when LOGINOUT creates the 
process rights list. 

rights id Unsigned longword denoting a rights identifier, 

which identifies an interest group in the 
context of the VMS security environment. 

This rights environment may consist of all or 
part of a user's user identification code (UIC). 

The basic component of the VMS protection 
scheme is an identifier. This 32-bit binary 
value represents various types of agents using 
the system. The types of agents represented 
include individual users, groups of users, and 
environments in which a process is operating. 

Identifiers have two formats in the rights 
database: UIC format and ID format. The 
high-order bits of the identifier value specify 
the format of the identifier. Two high-order 
zero bits identify a UIC format identifier; bit 
31, set to 1, identifies an ID format identifier. 


Each UIC identifier is unique and represents 
a system user. The UIC identifier contains 
the two high-order bits that designate format, 
a member field, and a group field. Member 
numbers range from 0 to 65,534; group 
numbers range from 1 to 16,382. 


31 


0 


00 


group 


member 


UIC Format 


ZK-1905-84 


Bit 31, set to 1, specifies ID format. Bits 30 
through 28 are reserved by DIGITAL. The 
remaining bits specify the identifier value. 


31 


0 


1000 


identifier 


ID Format 


ZK-1906-84 
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Table 2-2 (Cont.) VMS Data Structures 

Data Structure Definition 

To the system, an identifier is a binary value; 
however, to make identifiers easy to use, the 
system translates the binary identifier value 
into an identifier name. The binary value and 
the identifier name are associated in the rights 
database. 


rab 


section_id 


section_name 


system _access_id 


time_name 

uic 

user_arg 


varying_arg 


An identifier name consists of 1 to 31 
alphanumeric characters and contains at least 
one nonnumeric character. An identifier name 
cannot consist entirely of numeric characters. 

It can include the characters A through Z, 
dollar signs ($) and underscores (_), as well 
as the numbers 0 through 9. Any lowercase 
characters are automatically converted to 
uppercase. 

Structure denoting an RMS record access 
block. A complete description of this structure 
is contained in the VMS Record Management 
Services Manual. 

Unsigned quadword denoting a global section 
identifier. This identifier specifies the version 
of a global section and the criteria to be used 
in matching that global section. 

Character string denoting 1 to 43-character 
global section name. This character string 
can be a logical name, but it must translate 
to a valid global section name. For more 
information on how the system translates 
logical names to global section names see 
the "Memory Management" section of the 
Introduction to VMS System Services. 

Unsigned quadword that denotes a system 
identification value that is to be associated 
with a rights database. 

Character string specifying a time value in VMS 
format. 

Unsigned longword denoting a user 
identification code (UIC). 

Unsigned longword denoting a user-defined 
argument. This longword is passed to a 
procedure as an argument, but the contents of 
the longword are defined and interpreted by 
the user. 

Unsigned longword denoting a variable 
argument. A variable argument can have 
variable types, depending on specifications 
made for other arguments in the call. 
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Table 2-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 

vector_byte_signed 

A homogeneous array whose elements are all 
signed bytes. 

vector_byte_unsigned 

A homogeneous array whose elements are all 
unsigned bytes. 

vector_longword_signed 

A homogeneous array whose elements are all 
signed longwords. 

vector_longword_unsigned 

A homogeneous array whose elements are all 
unsigned longwords. 

vector_quadword_signed 

A homogeneous array whose elements are all 
signed quadwords. 

vector_quadword_unsigned 

A homogeneous array whose elements are all 
unsigned quadwords. 

vector_word_signed 

A homogeneous array whose elements are all 
signed words. 

vector_word_unsigned 

A homogeneous array whose elements are all 
unsigned words. 

word-signed 

This VMS data type is the same as the data 
type "word integer (signed)" in Table 2-3. 

word-unsigned 

This VMS data type is the same as the data 
type "word (unsigned)" in Table 2-3. 


2.3.2 Type Entry 


When a calling program passes an argument to a Run-Time Library routine, 
the routine expects the argument to be of a particular data type. The type 
entry indicates the expected data type for each argument. 

Properly speaking, an argument does not have a data type; rather, the data 
specified by an argument has a data type. The argument is merely the 
vehicle for the passing of data to the called routine. Nevertheless, the phrase 
"argument data type" is frequently used to describe the data type of the data 
that is specified by the argument. 

The following list contains the data types allowed by the VAX Procedure 
Calling and Condition Handling Standard. 

Table 2-3 VAX Data Types 

Data Type Symbolic Code 


Absolute date and time 
Byte integer (signed) 

Bound label value 
Bound procedure value 
Byte (unsigned) 

COBOL intermediate temporary 


DSC$K_DTYPE_ADT 

DSC$K_DTYPE_B 

DSC$K_DTYPE_BLV 

DSC$K_DTYPE_BPV 

DSC$K_DTYPE_BU 

DSC$K_DTYPE_CIT 
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Table 2-3 (Cont.) VAX Data Types 


Data Type 

Symbolic Code 

D_floating 

DSC$K_DTYPE_D 

D_floating complex 

DSC$K_DTYPE_DC 

Descriptor 

DSC$K_DTYPE_DSC 

F_floating 

DSC$K_DTYPE_F 

F_floating complex 

DSC$K _DT YPE _FC 

G_floating 

DSC$K_DTYPE_G 

G_floating complex 

DSC$K_DTYPE_GC 

H —floating 

DSC$K_DTYPE_H 

H_floating complex 

DSC$K_DTYPE_HC 

Longword integer (signed) 

DSC$K_DTYPE_L 

Longword (unsigned) 

DSC$K_DTYPE_LU 

Numeric string, left separate sign 

DSC$K_DTYPE_NL 

Numeric string, left overpunched sign 

DSC$K_DTYPE_NLO 

Numeric string, right separate sign 

DSC$K_DTYPE_NR 

Numeric string, right overpunched sign 

DSC$K_DTYPE_NRO 

Numeric string, unsigned 

DSC$K_DTYPE_NU 

Numeric string, zoned sign 

DSC$K_DTYPE_NZ 

Octaword integer (signed) 

DSC$K_DTYPE_0 

Octaword (unsigned) 

DSC$K_DTYPE_OU 

Packed decimal string 

DSC$K_DTYPE_P 

Quadword integer (signed) 

DSC$K_DTYPE_Q 

Quadword (unsigned) 

DSC$K_DTYPE_QU 

Character string 

DSC$K_DTYPE_T 

Aligned bit string 

DSC$K_DTYPE_V 

Varying character string 

DSC$K_DTYPE_VT 

Unaligned bit string 

DSC$K_DTYPE_VU 

Word integer (signed) 

DSC$K_DTYPE_W 

Word (unsigned) 

DSC$K_DTYPE_WU 

Unspecified 

DSC$K_DTYPE_Z 

Procedure entry mask 

DSC$K_DTYPE _ZEM 

Sequence of instruction 

DSC$K_DTYPE_ZI 
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2.3.3 






Access Entry 


The argument access entry describes the way in which the called routine 

accesses the data specified by the argument. The following three methods of 

access are the most common. 

1 Read only. Data upon which a routine operates, or data needed by the 
routine to perform its operation, must be read by the called routine. Such 
data is also called input data. When an argument specifies input data, the 
access entry shows "read only". 

The term "only" is present to indicate that the called routine does not 
both read and write (that is, "modify") the input data. Thus, input data 
supplied by a variable is preserved when the called routine completes 
execution. 

2 Write only. Data that the called routine returns to the calling routine 
must be written into a location where the calling routine can access it. 
Such data is also called output data. When an argument specifies output 
data, the access entry shows "write only". 

The term "only" is present to indicate that the called routine does not 
read the contents of the location either before or after it writes into the 
location. 

3 Modify. When an argument specifies data that is both read and written 
by the called routine, the access entry shows "modify". In this case, 
the called routine reads the input data, uses it in its operation, and 
then overwrites the input data with the results (the output data) of the 
operation. Thus, when the called routine completes execution, the input 
data specified by the argument is lost. 

The following is a complete list of the access types allowed by the VAX 

Procedure Calling and Condition Handling Standard. 

• Read only 

• Write only 

• Modify 

• Function call (before return) 

• JMP after unwind 

• Call after stack unwind 

• Call without stack unwind 
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2.3.4 Mechanism Entry 

The way in which an argument specifies the actual data to be used by the 
called routine is defined in terms of the argument passing mechanism. There 
are three types of passing mechanisms. 

1 By value. When an argument contains the actual data to be used by 
the routine, the data is said to be passed to the routine "by value". The 
argument therefore contains a copy of the actual data. Note that since an 
actual argument in an argument list is only one longword in length, only 
data that can be represented in one longword can be passed by value. 

2 By reference. When an argument contains the address of the data to be 
used by the routine, the data is said to be passed "by reference". In this 
case, the argument is a pointer to the actual data. 

3 By descriptor. When an argument contains the address of a descriptor, 
the data is said to be passed "by descriptor". A descriptor consists of two 
or more longwords (depending on the type of descriptor used), which 
describe the location, length, and data type of the data to be used by the 
called routine. In this case, the argument is a pointer to a descriptor that 
itself is a pointer to the actual data. 
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Figure 2-1 illustrates the three passing mechanisms. 

Figure 2-1 Routine Argument Passing Mechanisms 


ARGUMENT LIST 


N 


ARG 1 


ARG 2 


ACTUAL VALUE 


ARG N 


(AP) 

(a) ARGUMENT PASSED BY VALUE 


ARG 1 


ARG 2 


POINTER TO 
ACTUAL VALUE 


ARG N 


(AP) 


(b) ARGUMENT PASSED BY REFERENCE 


DATA 


ACTUAL VALUE 


=0 


DATA 



Note: ARG 1. ARG 2, and ARG N 
can be passed by value, by 
reference, or by descriptor 
in any of these examples. 


:(AP) = argument pointer 
N = number of arguments 

ZK-1962-84 
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Table 2-4 contains a list of the passing mechanisms allowed by the VAX 
Procedure Calling and Condition Handling Standard: 


Table 2-4 Passing Mechanisms 


Passing Mechanism 

Descriptor Code 

By value 

N/A 

By reference 

N/A 

By reference, array reference 

N/A 

By descriptor 

N/A 

By descriptor, fixed-length 

DSC$K_CLASS_S 

By descriptor, dynamic string 

DSC$K_CLASS_D 

By descriptor, array 

DSC$K_CLASS_A 

By descriptor, procedure 

DSC$K_CLASS_P 

By descriptor, decimal string 

DSC$K_CLASS_SD 

By descriptor, noncontiguous array 

DSC$K_CLASS_NCA 

By descriptor, varying string 

DSC$K_CLASS_VS 

By descriptor, varying string array 

DSC$K_CLASS_VSA 

By descriptor, unaligned bit string 

DSC$K_CLASS_UBS 

By descriptor, unaligned bit array 

DSC$K_CLASS_UBA 

By descriptor, string with bounds 

DSC$K_CLASS_SB 

By descriptor, unaligned bit string 
with bounds 

DSC$K_CLASS_UBSB 


2.3.5 Explanatory Text Entry 

For each argument, one or more paragraphs of explanatory text follow the 
usage, type, access, and mechanism entries. The first paragraph is highly 
structured and always contains the following items of information. 

1 An initial sentence fragment that describes: (1) the nature of the data 
specified by the argument and (2) the way in which the routine uses 
this data. For example, if an argument were supplying a number that the 
routine was to convert to another data type, the initial sentence fragment 
would be something like the following: "number that is to be converted 
to the such-and-such data type." 

2 A sentence expressing the data type and passing mechanism of the 
argument data. 

• If the passing mechanism is "by value", this sentence says something 
like the following: "The xxx argument is an unsigned longword 
containing the such-and-such data." 

• If the passing mechanism is "by reference", this sentence says 
something like the following: "The xxx argument is the address 
of a data type that contains the such-and-such data." 
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• If the passing mechanism is "by descriptor", this sentence says 

something like the following: "The xxx argument is the address of a 
descriptor pointing to the such-and-such data." 

Additional explanatory paragraphs appear for each argument as needed. 

For example, some arguments specify complex data consisting of many 
discrete fields, each of which has a particular purpose and use. In such 
cases, additional paragraphs provide detailed descriptions of each such field, 
symbolic names for the fields, if any, and guidance relating to their use. 


2.4 Condition Values Returned Heading 

A condition value is an unsigned longword that has several uses in the VAX 
architecture. 

• It indicates the success or failure of a called procedure. 

• It describes an exception condition when an exception is signaled. 

• It identifies system messages. 

• It reports program success or failure to the command language level. 

The documentation heading "Condition Values Returned" describes the 
condition values returned by the routine when it completes execution 
without generating an exception condition. This condition value describes 
the completion status of the operation. 

If a called routine generates an exception condition during execution, the 
exception condition is signaled; the exception condition is then handled by 
a condition handler (either user-supplied or system-supplied). Depending 
on the nature of the exception condition and the condition handler that 
handles the exception condition, the called routine will either continue 
normal execution or terminate abnormally. 

If a called Run-Time Library routine executes without generating an exception 
condition, the called routine either returns a condition value or signals an 
error condition; a few procedures both return a condition value and signal 
an error condition. In the documentation of each routine, the method used 
to return the condition value is indicated in the heading title itself. These 
heading titles are discussed individually in the subsections that follow. 

Under either of these headings, a two-column list gives the symbolic code 
for each condition value that the routine can return and its accompanying 
description. This description explains whether the condition value indicates 
success or failure, and if failure, what user action may have caused the failure 
and what can be done to correct it. Condition values that indicate success are 
listed first. 
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Symbolic codes for condition values are system defined. The symbolic code 
defined for each condition value equates to a number that is identical to the 
longword condition value when interpreted as a number. In other words, 
though the condition value consists of several fields, each of which can be 
interpreted individually for specific information, the entire longword condition 
value itself can be interpreted as an unsigned longword integer, which has an 
equivalent symbolic code. 

The following subsections discuss the ways in which a called routine returns 
condition values. 


2.4.1 Condition Values Returned 

When the called routine returns a condition value in general register RO, the 
possible condition values that the routine can return are listed under the 
"Condition Values Returned" heading. Most routines return a condition value 
in this way. 


2.4.2 Condition Values Signaled 

When the called routine signals its condition value (instead of returning it in 
RO), the possible condition values that the routine can signal are listed under 
the "Condition Values Signaled" heading. 

Routines that signal condition values as a way of indicating the completion 
status do so because these routines are returning actual data in one or more 
of the general registers. Since register RO is used to convey data, it cannot 
also receive the condition value. 

As mentioned, the signaling of condition values occurs whenever a routine 
generates an exception condition, regardless of how the routine returns its 
completion status under normal circumstances. 
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The VAX Procedure Calling and Condition Handling Standard describes the 
mechanisms used by all VAX languages for invoking routines and passing 
data between them. In effect, this standard describes the interface between 
your program and the Run-Time Library routines that your program calls. 

This chapter describes the basic methods for coding calls to Run-Time Library 
routines from any VAX language. 

In simple terms, when you call a Run-Time Library routine from your 
program, you must furnish whatever arguments the routine requires. When 
the routine completes execution, in most cases it returns control to your 
program. If the routine returns a status code, your program should check 
the value of the code to determine whether or not the routine completed 
successfully. If the return status indicates an error, you may want to change 
the flow of execution of your program to handle the error before returning 
control to your program. 

Overview 

When you log in, the VMS system creates a process that exists until you log 
out. When you run a program, the system activates an executable image in 
your process. This image consists of a set of user procedures. 

From the Run-Time Library's point of view, user procedures are procedures 
that exist outside the Run-Time Library and that can call Run-Time Library 
routines. User procedures can additionally call other user procedures that are 
either supplied by DIGITAL or written by you. According to this definition, 
then, the Run-Time Library views a VAX native-mode language compiler as a 
set of user procedures, since the compiler generates code that calls Run-Time 
Library routines. When you write a program that calls a Run-Time Library 
routine, the Run-Time Library views your program as a user procedure. 

The main program, or main procedure, is the first user procedure that the 
system calls after calling a number of initialization procedures. A user 
program, then, consists of the main program and all of the other user 
procedures that it calls. 

Figure 3-1 shows the calling relationships among a main program, other user 
procedures, library routines, and the VMS operating system. In this figure, 
CALL indicates that the calling procedures requested some information or 
action; RETURN indicates that the called procedure returned the information 
to the calling procedure or performed the action. 

Although library routines can always call other library routines or the VMS 
operating system, they can call user procedures only in the following cases: 

• When a user procedure establishes its own condition handler. For 
example, LIB$SIGNAL operates by searching for and calling user 
procedures that have been established as condition handlers (see the 
VMS RTL Library (LIB$) Manual for more information). 
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Figure 3-1 Calling the Run-Time Library 



ZK-4262-85 


• When a user procedure passes to a routine the address of another 

procedure that the library will call later. For example, when your program 
calls LIB$SHOW_TIMER, you can pass the address of an action routine 
that LIB$SHOW_TIMER will call to process timing statistics. 


3.2 Call Formats 

Each Run-Time Library routine requires a specific calling sequence. This 
calling sequence indicates the elements that you must include when calling 
the routine, and the order of those elements. The form of a calling sequence 
is explained below. 

Call Type 

A calling sequence first specifies the type of call being made. A library routine 
can be invoked by a CALLS or CALLG instruction or by a JSB instruction. 

• CALLS - Call Procedure with Stack Argument List instruction 

• CALLG - Call Procedure with General Argument List instruction 

• JSB - Jump to Subroutine instruction 

Note that the following restrictions apply to the different types of calls. 

• High-level languages do not differentiate between CALLS and CALLG. 
They use a CALL statement or a function reference to invoke a Run-Time 
Library routine. 

• MACRO does not differentiate between functions and subroutines in its 
CALLS and CALLG instructions. 
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• Only MACRO and BLISS programs can explicitly access the JSB entry 
points that are provided for some routines in the Run-Time Library. You 
cannot write a program to access the JSB entry points directly from a 
high-level language. 


Facility Prefix and Routine Name 

Each routine is identified by a unique entry point name, consisting of the 
facility prefix (DTK$, LIB$, MTH$, and so on) and the procedure name (for 
example, MTH$SIN). Section 3.3 provides more detailed information on entry 
point naming conventions. 


Argument List 

Arguments passed to a routine must be listed in your program in the order 
shown in the format section of the routine description. Each argument 
has four characteristics: VMS usage, data type, access type, and passing 
mechanism. These characteristics are described in Chapter 2 of this manual. 

Some arguments are optional. Optional arguments are indicated by brackets 
in the routine descriptions. When your program invokes a Run-Time Library 
routine using a CALL entry point, you can omit optional arguments at the 
end of the argument list. If the optional argument is not the last argument 
in the list, you must either pass a zero by value or use a comma as a place 
holder to indicate the place of the omitted argument. 

Optional arguments apply only to the CALL entry points. JSB entry points do 
not have optional arguments; all specified registers are used. 

For example, the call format for a procedure with two optional arguments is 
as follows: 


LIB$GET_INPUT get-str [,prompt-str] [,out-len] 

A FORTRAN program could include any one of the following calls to this 
procedure: 


ST AT - LIB$GET_INPUT 
ST AT = LIB$GET_INPUT 
ST AT - LIB$GET_INPUT 
ST AT = LIB$GET_INPUT 
ST AT = LIB$GET_INPUT 
ST AT = LIB$GET_INPUT 
ST AT - LIB$GET_INPUT 


(GET_STR,PROMPT,LENGTH) 

(GET_STR,PROMPT) 

(GET_STR,PROMPT,) 

(GET—STR,,LENGTH) 
(GET-STR) 

(GET-STR,) 

(GET_STR, %VAL(0)) 


The following examples illustrate the standard mechanism for calling an 
external procedure, subroutine, or function in most high-level languages. 


BASIC 

CALL LIB$MOVTC(SRC, FILL, TABLE, DEST) 
STATUS - LIB$GET_INPUT(STRING, 'NAME:') 
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BUSS 

LOCAL 

MSG—DESC : BLOCK [8,BYTE]; 

MSG—DESC [DSC$B_CLASS] *= DSC$K_CLASS_S, 

MSG—DESC [DSC$B_DTYPE] - DSC$K_DTYPE—T; 

MSG_DESC [DSC$W_LENGTH] - 5; 

MSG—DESC [DSC$A_POINTER] - MSG; 

STATUS = LIB$PUT_OUTPUT(MSG_DESC); 

COBOL 

CALL LIBSMOVTC USING BY DESCRIPTOR 
SRC, 

FILL, 

TABLE, 

DEST, 

GIVING RET-STATUS. 

FORTRAN 

CALL LIB$MOVTC(SRC, FILL, TABLE, DEST) 

STATUS = LIB$GET_INPUT (STRING, 'NAME:') 

Pascal 

RET_STATUS := LIB$MOVTC (SRC, FILL, TABLE, DEST); 

PL/I 

CALL LIB$MOVTC(SRC, FILL, TABLE, DEST); 

STATUS - LIB$GET_INPUT(STRING, 'NAME:'); 

As these examples show, VAX languages use varying call forms. Each 
language user's guide gives specific information on calling the Run-Time 
Library from that language. 

In MACRO, a calling sequence takes one of three forms, as illustrated by the 
following examples: 

CALLS #2,G"LIB$GET_INPUT 

CALLG ARGLIST, G"LIB$GET_VM 

JSB G“MTH$SIN_R4 


3.3 Run-Time Library Naming Conventions 

This section explains the naming conventions that the Run-Time Library 
follows for its entry point names, return status codes, and condition value 
symbols. 
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3.3.1 Entry Point Names 

Run-Time Library entry points follow the VAX conventions for naming global 
symbols. A global entry point takes the following general form: 

fac$symbol 

The elements which make up this format represent the following: 

FAC A 2- or 3-character facility name 
SYMBOL A 1- to 27-character symbol 

The facility names are maintained in a systemwide DIGITAL registry. A 
unique, 12-bit facility number is assigned to each facility name for use in 
(1) condition value symbols, and (2) condition values in procedure return 
status codes, signaled conditions, and messages. The high-order bit of this 
number is 0 for facilities assigned by DIGITAL and 1 for those assigned by 
Computer Special Services (CSS) and customers. For further information, 
refer to the VAX Procedure Calling and Condition Handling Standard. 

The Run-Time Library facility names are as follows: 


DTK$ 

DECtalk routines 

LIB$ 

Library routines 

MTH$ 

Mathematics routines 

OTS$ 

General purpose routines 

PPL$ 

Parallel processing routines 

SMG$ 

Screen management routines 

STR$ 

String handling routines 


3.3.2 JSB Entry Point Names 

JSB entry point names follow the naming conventions explained in the 
previous section, except that they include a suffix indicating the number of 
the highest register accessed or modified. This helps ensure that the calling 
program and the called routine will agree on the number of registers that the 
called routine is going to change. 

The following example illustrates the MACRO code that invokes the library 
routine MTH$SIN_R4 by means of a JSB instruction. As indicated in the JSB 
entry point name, this routine uses RO through R4. 

JSB G"MTH$SIN_R4 ;F-floating sine uses RO to R4 

JSB entry points are available only to MACRO and BLISS programs. No VAX 
high-level language provides a mechanism for accessing JSB entry points 
explicitly. 
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3.3.3 Function Return Values 


Some Run-Time Library routines return a function value. This is generally 
a 32-bit value returned in register RO or a 64-bit value returned in registers 
R0:R1. When a routine returns a function value, it cannot use RO and R1 
to return a status code. Therefore, such a procedure signals errors rather 
than returning a status. This is explained in more detail in Chapter 2 of this 
manual. 

In high-level languages, statuses or function return values in RO appear as the 
function result. 


3.3.4 Facility Return Status and Condition Value Symbols 



Library return status and condition value symbols have the following general 
form: 

fac$_abcmnoxyz 

The elements which make up this format represent the following: 


fac The 2- or 3-letter facility symbol 

abc The first three letters of the first word of the associated message 

mno The first three letters of the next word 

xyz The first three letters of the third word, if any 



Articles and prepositions are not considered significant words in this format. 
If a significant word is only two letters long, an underscore is used to fill 
out the third space. Some examples follow. Note that in most facilities the 
normal or success symbol is an exception to the convention just described. 


SS$_NORMAL 

LIB$_INSVIRMEM 

MTH$_FLOOVEMAT 

OTS$_FATINTERR 


Routine successfully completed 
Insufficient virtual memory 

Floating overflow in mathematics library procedure 

Fatal internal error in a language-independent support 
procedure 

Screen buffer overflow 



LIB$_SCRBUFOVF 


3.3.5 Argument Passing Mechanisms 


A calling program passes an argument list of longwords to a called routine; 
each longword in the argument list specifies a single argument. The called 
routine interprets each argument using one of three standard passing 
mechanisms: by value, by reference, or by descriptor. 
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3.3.5.1 Passing Arguments by Value 

When your program passes an argument using the by value mechanism, 
the argument list entry contains the actual uninterpreted 32-bit value of 
the argument. The value mechanism is usually used to pass constants. For 
example, to pass the constant 100 by value, the calling program puts 100 
directly in the argument list. 

All VAX high-level languages require you to specify the by-value mechanism 
explicitly when you call a procedure that accepts an argument by value. 
FORTRAN, for example, uses the %VAL built-in function, while COBOL uses 
the BY VALUE qualifier on the CALL [USING] statement. 

A FORTRAN program calls a procedure using the by-value mechanism as 
follows: 

INCLUDE ’($SSDEF)’ 

CALL LIB$ST0P C/.VAL(SS$_INT0VF)) 

A BLISS program calls this procedure as follows: 

LIB$SIGNAL (SS$_INT0VF) 

The equivalent MACRO code is as follows: 

PUSHL #SS$_INT0VF : Push longword by value 

CALLS #i,G*LIB$SIGNAL ; Call LIB$SIGNAL 

Note: Because the Run-Time Library is intended to be called from higher- 

level languages, most Run-Time Library routines receive arguments by 
reference, rather than by value, at their CALL entry points. 


3.3.5.2 Passing Arguments by Reference 

When your program passes arguments using the by reference mechanism, 
the argument list entry contains the address of the location that contains the 
value of the argument. For example, if variable x is allocated at location 1000, 
the argument list entry will contain 1000, the address of the value of x. 

Most languages pass scalar data by reference by default. Therefore, if you 
simply specify x in the CALL statement or function invocation, the language 
automatically passes the value stored at the location allocated to x to the 
Run-Time Library routine. 

A BLISS program calls a procedure using the by-reference mechanism as 
follows: 

LIB$FLT_UNDER C/,REF(1)) 


The equivalent MACRO code is as follows: 


ONE: 

.LONG 

1 

; Longword value 1 


PUSHAL 

ONE 

; Push address of longword 


CALLS 

#1,G~LIB$FLT_UNDER 

; Call LIB$FLT_UNDER 
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3.3.5.3 Passing Arguments by Descriptor 

When a procedure specifies that an argument is passed by descriptor, the 
argument list entry must contain the address of a descriptor for the argument. 
This mechanism is used to pass more complicated data. A descriptor includes 
at least the following fields: 


Symbol 

Description 

DSC$W_LENGTH 

Length of data (or DSC$W_MAXSTRLEN, maximum length, 
for varying strings) 

DSC$B_DTYPE 

Data type 

DSC$B_CLASS 

Descriptor class code 

DSC$ A-POINTER 

Address at which the data begins 


The VAX Procedure Calling and Condition Handling Standard describes these 
fields in greater detail. 


VAX high-level languages include extensions for passing arguments by 
descriptor. When you specify by descriptor in these languages, the compiler 
creates the descriptor, defines its fields, and passes the address of the 
descriptor to the Run-Time Library routine. In some languages, by descriptor 
is the default passing mechanism for certain types of arguments, such as 
character strings. For example, the default mechanism for passing strings in 
VAX BASIC is by descriptor. 

100 COMMON STRING GREETING = 30 

200 CALL LIB$PUT.SCREEN(GREETING) 

The default mechanism for passing strings in COBOL, however, is by 
reference. Therefore, when passing a string argument to a Run-Time Library 
routine from a COBOL program, you must specify BY DESCRIPTOR for the 
string argument in the CALL statement. 

CALL LIB$PUT_0UTPUT USING BY DESCRIPTOR GREETING. 

In MACRO or BLISS, you must define the descriptor's fields explicitly 
and push its address onto the stack. Following is the MACRO code that 
corresponds to the previous examples. 


MSGDSC: .WORD LEN 

.BYTE DSC$K_DTYPE_T 
.BYTE DSC$K_CLASS_S 
.ADDRESS MSG 

MSG: .ASCII/Hello/ 

LEN = .-MSG 

.ENTRY EXl.-MO 

PUSHAQ MSGDSC 

CALLS #1.G"LIB$PUT_0UTPUT 

RET 

.END EX1 


; DESCRIPTOR: DSC$W_LENGTH 
; DSC$B_DTYPE 
; DSC$B_CLASS 
; DSC$A_P0INTER 

: String itself 

; Define the length of the string 

; Push address of descriptor 
; Output the string 
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The equivalent BLISS code looks like this: 

MODULE BLISS1 (MAIN = BLISS1. ! Example of calling LIB$PUT_OUTPUT 

IDENT = ’1-001’, 

ADDRESSING_MODE(EXTERNAL = GENERAL)) = 

BEGIN 

EXTERNAL ROUTINE 

LIB$ST0P, ! Stop execution via signaling 

LIB$PUT_OUTPUT; ! Put a line to SYS$OUTPUT 

FORWARD ROUTINE 

BLISS1 : NOVALUE; 

LIBRARY ’SYS$LIBRARY:STARLET.L32’; 

ROUTINE BLISS1 ! Routine 

: NOVALUE = 


BEGIN 

! + 

! Allocate the necessary local storage. 

! - 

LOCAL 

STATUS, ! Return status 

MSG.DESC : BLOCK [8, BYTE]; ! Message descriptor 


BIND 

MSG = UPLIT(’HELLO’); 


! + 

! Initialize the string descriptor. 

MSG.DESC [DSC$B_CLASS] = DSC$K_CLASS_S; 

MSG_DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T; 

MSG_DESC [DSC$W_LENGTH] = 5; 

MSG.DESC [DSC$A_POINTER] = MSG; 

! + 

! Put out the string. Test the return status, 
i if it is not a success, then signal the RMS error. 

j - 

STATUS = LIB$PUT_OUTPUT(MSG_DESC); 

IF NOT .STATUS THEN LIB$ST0P(.STATUS); 

END; I End of routine BLISS1 

END I End of module BLISS1 

ELUDOM 


3.4 Passing Scalars as Arguments 

When you are passing an input scalar value to a Run-Time Library routine, 
you usually pass it either by reference or by value. You usually pass output 
scalar arguments by reference to Run-Time Library routines. An output scalar 
argument is the address of a location where some scalar output of the routine 
will be stored. 
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Passing Arrays as Arguments 

Arrays are passed to Run-Time Library routines by reference or by descriptor. 

Sometimes, the routine knows the length and dimensions of the array to be 
received, as in the case of the table passed to LIB$CRC_TABLE. Arrays such 
as this are normally passed by reference. 

In other cases, the routine will actually analyze and operate on the input 
array. The routine does not necessarily know the length or dimensions 
of such an input array, so that a descriptor is necessary to provide the 
information the routine needs to accurately describe the array. 


Passing Strings as Arguments 

Strings are passed by descriptor to Run-Time Library routines. The Run-Time 
Library routine recognizes the following descriptors: 


Descriptor 

Descriptor Class Code 

Numeric Value 

Unspecified 

DSC$K_CLASS_Z 

0 

Fixed-length 

DSC$K_CLASS_S 

1 

Dynamic 

DSC$K_CLASS_D 

2 

Array 

DSC$K_CLASS_A 

4 

Scaled decimal 

DSC$K_CLASS_SD 

9 

Noncontiguous array 

DSC$K_CLASS_NCA 

10 

Varying-length 

DSC$K CLASS VS 

11 


A Run-Time Library routine writes strings according to the following three 
types of semantics: 

• Fixed length, characterized by an address and a constant length 

• Varying length, characterized by an address, a current length, and a 
maximum length 

• Dynamic, characterized by a current address and a current length 


Combinations of Descriptor Class and Data Type 

Some combinations of descriptor class and data type are not permitted, either 
because they are not meaningful or because the VAX Procedure Calling and 
Condition Handling Standard does not recognize them. Furthermore, the 
same function may be performed with more than one combination. This 
section describes the restrictions on the combinations of descriptor classes 
and data types. These restrictions help to keep procedure interfaces simple 
by allowing a procedure to accept a limited set of argument formats without 
sacrificing functional flexibility. 

Tables 3-1 to 3-3 show all possible combinations of descriptor classes and 
data types. For example. Table 3-1 shows that your program can pass an 
argument to a Run-Time Library routine whose descriptor class is DSC$K_ 
CLASS—A (array descriptor) and whose data type is unsigned byte (DSC$K_ 
DTYPE—BU). The VAX Procedure Calling and Condition Handling Standard 
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does not permit your program to pass an argument whose descriptor class is 
DSC$K_CLASS_D (decimal string) and whose data type is unsigned byte. 


Table 3-1 Atomic Data Types and Descriptor Classes 



DSC$K CLASS 



_s 
= 1 

_D 
= 2 

_V 
= 3 

_A 
= 4 

_P 

= 5 

_SD 
= 9 

_NCA 
= 10 

_vs 
= 11 

VSA 

= 12 

UBS 

= 13 

UBA 

= 14 

BFA 

= 191 

DSC$K DTYPE 0 = 26 

Yes 

_ 

- 

Yes 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DT YPE F = 10 

Yes 

_ 

_ 

Yes 

Yes 

Yes 

Yes 

- 

- 

Yes 

Yes 

Yes 

DSC$K DTYPE D = 11 

Yes 

_ 

_ 

Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

Yes 

DSC$K DTYPE G = 27 

Yes 

_ 

_ 

Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE H = 28 

Yes 

_ 

_ 

Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE FC = 12 

Yes 

_ 

_ 

Yes 

Yes 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE DC = 13 

Yes 

_ 

_ 

Yes 

Yes 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE GC = 29 

Yes 

_ 

- 

Yes 

Yes 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE HC = 30 

- 

- 

- 

- 

- 

- 

- 

- 

- 

- 

- 

- 

DSC$K_DTYPE_CIT = 31 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

— 

— 

— 


Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


ZK-4267/1-85 
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Table 3-1 (Cont.) Atomic Data Types and Descriptor Classes 








DSC$K. 

.CLASS 










_S 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_VS 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$K_DTYPE_Z 

= 

0 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K DTYPE BU 

= 

2 

Yes 

- 

- 

Yes 

Yes 

- 

Yes 

- 

- 

Yes 

Yes 

— 

DSC$K DTYPE WU 

= 

3 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

_ 

DSC$K_DTYPE_LU 

= 

4 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K DTYPE QU 

= 

5 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE OU 

= 

25 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE B 

= 

6 

Yes 

- 

- 

Yes 

Yes 

Yes 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K DTYPE W 

= 

7 

Yes 

- 

- 

Yes 

Yes 

Yes 

Yes 

- 

- 

Yes 

Yes 

Yes 

DSC$K DTYPE L 

= 

8 

Yes 

- 

- 

Yes 

Yes 

Yes 

Yes 

- 

- 

Yes 

Yes 

Yes 

DSC$K DTYPE Q 

= 

9 

Yes 

- 

- 

Yes 

- 

Yes 

Yes 

- 

- 

- 

- 

- 



Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 


The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 
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Table 3-2 String Data Types and Descriptor Classes 





DSC$K CLASS 




_s 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_VS 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$X_DTYPE_V 

= 

1 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K DTYPE T 

= 

14 

Yes 

Yes 

- 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

DSC$K_DTYPE_NU 

= 

15 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_NL 

= 

16 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE NLO 

= 

17 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_NR 

= 

18 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_NLR 

= 

19 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_NZ 

= 

20 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_P 

= 

21 

Yes 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE VT 

= 

37 

- 

- 

- 

- 

- 

- 

- 

Yes 

Yes 

- 

- 

- 

DSC$K_DTYPE_VU 

= 

34 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 


Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 
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Table 3-3 Miscellaneous Data Types and Descriptor Classes 





DSC$K CLASS 




_s 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_VS 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$K_DTYPE_ZI 

= 

22 

Yes 

- 

- 

- 

- 

* 

- 

- 

- 

- 

- 

- 

DSC$K_DTYPE_ZEM 

= 

23 

Yes 

- 

- 

- 

- 

* 

- 

- 

- 

- 

- 

- 

DSC$K_DTYPE_DSC 

= 

3 













(See Note 3) 



- 

- 

- 

Yes 

- 

* 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_BPV 

= 

32 

Yes 

- 

- 

- 

- 

* 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_BLV 

= 

33 

Yes 

- 

- 

- 

- 

* 

Yes 

- 

- 

- 

- 

- 


Key 


Yes 

The Calling Standard allows this combination of class and data type. 

♦ 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


ZK-4265-85 


Note 

1 Class types DSC$K_CLASS_PI (6) and DSC$K_CLASS_JI (8) are 
considered obsolete. 

2 Class type DSC$K_CLASS_J (7) is reserved for use by the debugger. 

3 A descriptor with data type DSC$K_DTYPE_DSC (24) points to a 
descriptor that has class DSC$K_CLASS_D (2) and data type 
DSC$K_DTYPE_T (14). All other class and data type combinations in 
the target descriptor are reserved for future definition in the standard. 

4 DSC$K_CLASS_P is used by VAX FORTRAN. No new VAX languages 
will use it. 

5 The scale factor for DSC$K_CLASS_SD is always a decimal data type. It 
does not vary with the data type of the data described by the descriptor. 

6 For DSC$K_CLASS_UBS and DSC$K_CLASS_UBA, the length field 
will specify the length of the data field in bits. For example, if the data 
type is unsigned word (DSC$K_DTYPE_WU), DSC$W_LENGTH 
equals 16. 
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3.8 Errors from Run-Time Library Routines 

A routine can indicate an error condition to the calling program either by 
returning a 32-bit condition value in RO as a completion code or by signaling 
the error. 

A completion code, also called a return status or condition value, is either a 
success (bit 0 = 1) or error condition value (bit 0 = 0). In an error condition 
value, the low-order three bits specify the severity of the error. Bits 27 
through 16 contain the facility number, and bits 15 through 3 indicate the 
particular condition. The high-order four bits are control bits. When the 
called procedure returns a condition value, the calling program can test RO 
and choose a recovery path. A general guideline to follow when testing for 
success or failure is that all success codes have odd values and all error codes 
have even values. 

When the completion code is signaled, the calling program must establish a 
handler to get control and take appropriate action. (See the VMS RTL Library 
(LIBS) Manual for a description of signaling and condition handling and more 
information on the condition value.) 


3.9 Calling a Library Procedure in MACRO 

This section describes how to code MACRO calls to library routines using a 
CALLS, CALLG, or JSB instruction. The routine descriptions that appear later 
in this manual describe the entry points for each routine. You can use either 
a CALLS or a CALLG instruction to invoke a procedure with a CALL entry 
point. You must use a JSB instruction to invoke a procedure with a JSB entry 
point. All MACRO calls are explicitly defined. 


3.9.1 MACRO Calling Sequence 

All Run-Time Library routines have a CALL entry point. Some routines 
also have a JSB entry point. In MACRO, you invoke a CALL entry point 
with a CALLS or CALLG instruction. To access a JSB entry point, use a JSB 
instruction. 

Arguments are passed to CALLS and CALLG entry points by a pointer to 
the argument list. The only difference between the CALLS and CALLG 
instructions is as follows: 

• For CALLS, the calling procedure pushes the argument list onto the stack 
(in reverse order) before performing the call. The list is automatically 
removed from the stack upon return. 

• For CALLG, the calling program specifies the address of the argument 
list, which can be anywhere in memory. This list remains in memory 
upon return. 

Both of these instructions have the same effect on the called procedure. 

JSB instructions execute faster than CALL instructions. They do not set up 
a new stack frame, do not change the enabling of hardware traps or faults, 
and do not preserve the contents of any registers before modifying them. For 
this reason, you must be careful when invoking a JSB entry point in order to 
prevent the loss of information stored by the calling program. 


3-15 










How to Call Run-Time Library Procedures 

3.9 Calling a Library Procedure in MACRO 


Whichever type of call you use, the actual reference to the procedure entry 
point should use general mode addressing (G“). This ensures that the linker 
and the image activator will be able to locate the module within the shareable 
image. 

In most cases, you have to tell a library routine where to find input values 
and store output values. You must select a data type for each argument when 
you code your program. Most routines accept and return 32-bit arguments. 

For input arguments of byte, word, or longword values, you can supply either 
a constant value, a variable name, or an expression in the Run-Time Library 
routine call. If you supply a variable name for the argument, the data type 
of the variable must be as large or larger than the data types that the called 
procedure requires. If, for example, the called procedure expects a byte in the 
range 0 to 100, you can use a variable data type of a byte, word, or longword 
with a value between 0 and 100. 

For each output argument, you must declare a variable of exactly the length 
required to avoid extraneous data. If, for example, the called procedure 
returns a byte value to a word-length variable, the leftmost eight bits of the 
variable (15:8) are not overwritten on output. Conversely, if a procedure 
returns a longword value to a word-length variable, it modifies variables in 
the next higher word. 


3.9.2 CALLS Instruction Example 

Before executing a CALLS instruction, you must push the necessary 
arguments on the stack. Arguments are pushed in reverse order; the last 
argument listed in the calling sequence is pushed first. The following 
example shows how a MACRO program calls the procedure that allocates 
virtual memory in the program region for LIB$GET_VM. 


.PSECT 

DATA 

PIC,USR,CON,REL,GBL,N0SHR,N0EXE.RD,WRT,N0VEC 

.LONG 

0 


; Longword to hold address of 
; allocated memory 

.LONG 

700 


; Number of bytes to allocate 

.PSECT 

CODE 

PIC,USR,CON,REL,GBL,SHR,EXE,RD,N0WRT,N0VEC 

.ENTRY 

PROG, ~M<> 


PUSHAL 

MEM 


Push address of longword 
to receive address of block 

PUSHAL 

LEN 


Push address of longword 
containing number of bytes 
desired 

CALLS 

#2, 

G‘LIB$GET_VM 

Allocate memory 

BLBC 

R0. 

1$ 

Branch if memory not available 

RET 



PUSHL 

R0 


Signal the error 

CALLS 

RET 

#1, 

G*LIB$SIGNAL 


.END 

PROG 



Because the stack grows toward location 0, arguments are pushed onto the 
stack in reverse order from the order shown in the general format for the 
routine. Thus, the base-address argument, here called START, is pushed 
first, and then the number-bytes argument, called LEN. Upon return from 
LIB$GET_VM, the calling program tests the return status (ret-status), which 
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is returned in RO and branches to an appropriate error routine if an error 
occurred. 


3.9.3 CALLG Instruction Example 

When you use the CALLG instruction, the arguments are set up in any 
location, and the call includes a reference to the argument list. The following 
example of a CALLG instruction is equivalent to the preceding CALLS 
example. 


ARGLST: 


.LONG 


2 

Argument list count 

.ADDRESS 

LEN 

Address of longword containing 




the number of bytes to allocate 

.ADDRESS 

START 

Address of longword to receive 




the starting address of the 
virtual memory allocated. 

LEN: .LONG 


20 

Number of bytes to allocate 

START: .BLKL 


1 

Starting address of the virtual 
memory. 

CALLG 

ARGLIST, G'LIB$GET_VM 

; Get virtual memory 

BLBC 

RO, 

ERROR 

; Check for error 

BRB 

10$ 




3.9.4 JSB Entry Points 

A procedure's JSB entry point name indicates the highest numbered register 
that the procedure modifies. Thus a procedure with a suffix Rn modifies 
registers RO through Rn. (You should always assume that RO and R1 are 
modified.) The calling program loads the arguments in the registers before 
the JSB instruction is executed. 

A calling program must use a JSB instruction to invoke a Run-Time Library 
routine by means of its JSB entry point. You pass arguments to a JSB entry 
point by placing them in registers in the following manner. 

NUM: .FLOAT 0.7853981 ; Constant Pl/4 

MOVF NUM, RO ; Set up input argument 

JSB G~MTH$SIN_R4 ; Call F-floating sine procedure 

; Return with value in RO 

In this example, R4 in the entry point name indicates that MTH$SIN_R4 
changes the contents of registers RO through R4. The routine does not 
reference or change the contents of registers R5 through Rll. 

The entry mask of a calling procedure should specify all the registers to be 
saved if the procedure invokes a JSB routine. This step is necessary because a 
JSB procedure does not have an entry mask, and thus has no way to specify 
registers to be saved or restored. 

For example, consider program A calling procedure B by means of a CALL 
entry point. 

• Procedure B modifies the contents of R2 through R6, so the contents of 
these registers are preserved at the time of the CALL. 

• Procedure B then invokes procedure C by means of a JSB entry point. 
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• Procedure C modifies registers RO through R7. 

• When control returns to procedure B, R7 has been modified, but when 
procedure B passes control back to procedure A, it restores only R2 
through R6. Thus the contents of R7 are unpredictable, and program A 
does not execute as expected. Procedure B should be rewritten so that R2 
through R7 are saved in procedure B's entry mask. 

A similar problem occurs if the stack is unwound, because unwinding the 
stack restores the contents of registers for each stack frame as it removes the 
previous frame. Because a JSB entry point does not create a stack frame, the 
contents of the registers before the JSB instruction will not be restored unless 
they were saved in the entry mask of the calling program. You do this by 
naming the registers to be saved in the calling program's entry mask, so a 
stack unwind correctly restores all registers from the stack. In the following 
example, the function Y=PROC(A,B) returns the value Y, where 
Y = SIN(A)*SIN(B). 


.ENTRY 

PROC. *M <R2 

MOVF 

04(AP) , RO 

JSB 

G*MTH$SIN_R4 

MOVF 

RO . R5 

MOVF 

08(AP) , RO 

JSB 

G~MTH$SIN_R4 

MULF 

R5 . RO 

RET 



Save R2:R5 
RO = A 
RO = SIN (A) 

Copy result to register 
not modified by MTH$SIN 
RO = B 
RO = SIN(B) 

RO = SIN(A)SIN(B) 

Return 


3.9.5 Return Status 


Your MACRO program can test for errors by examining segments of the 
32-bit status code returned by a Run-Time Library routine. 

To test for errors, check for a zero in bit zero, using a Branch on Low Bit Set 
(BLBS) or Branch on Low Bit Clear (BLBC) instruction. 

To test for a particular condition value, compare the 32 bits of the return 
status with the appropriate return status symbol, using a Compare Long 
(CMPL) instruction or the Run-Time Library routine LIB$MATCH_COND. 

There are three ways to define a symbol for the condition value returned by 
a Run-Time Library routine so that you can compare the value in RO with a 
particular error code: 

• Using the .EXTRN symbol directive. This causes the assembler to 
generate an external symbol declaration. 

• Using the $facDEF macro call. Calling the $LIBDEF macro, for example, 
causes the assembler to define all LIB$ condition values. 

• By default. The assembler automatically declares the condition value as 
an external symbol that is defined as a global symbol in the Run-Time 
Library. 

The following example asks for the user's name. It then calls the Run¬ 
Time Library routine LIB$GET_INPUT to read the user's response from 
the terminal. If the string returned is longer than 30 characters (the space 
allocated to receive the name), LIB$GET_INPUT returns in RO the condition 
value equivalent to the error LIB$_INPSTRTRU, 'input string truncated.' This 
value is defined as a global symbol by default. The example then checks for 
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3.9.6 



the specific error by comparing LIB$_INPSTRTRU with the contents of RO. 
If LIB$_INPSTRTRU is the error returned, the program considers that the 
routine executed successfully. If any other error occurs, the program handles 
it as a true error. 



$SSDEF 


Define SS$ symbols 


SDSCDEF 


Define DSC$ symbols 


.PSECT 

$DATA 


PROMPT. 

D: 


Descriptor for prompt 


.WORD 

PROMPT.LEN 

Length field 


.BYTE 

DSC$K_DTYPE_T 

Type field is text 


.BYTE 

DSC$K_CLASS_S 

Class field is string 


.ADDRESS 

PROMPT 

Address 

PROMPT: 

.ASCII 

/NAME: / 

String descriptor 

PROMPT. 

LEN = . - 

PROMPT 

Calculate length of 
string 

STR.LEN 

[ = 30 


Use 30-byte string 

STRING.D: 


Input string descriptor 


.WORD 

STR.LEN 

Length field 


.BYTE 

DSC$K_DTYPE_T 

Type field in text 


.BYTE 

DSC$K_CLASS_S 

Class field is string 


.ADDRESS 

STR.AREA 

Address 

STR.AREA: .BLKB 

STR.LEN 

Area to receive string 



.PSECT SCODE 
.ENTRY START , ~M<> 




PUSHAQ PROMPT.D 

Push address of prompt 
descriptor 



PUSHAQ STRING.D 

Push address of string 
descriptor 



CALLS #2 . G*LIB$GET_INPUT 

Get input string 



BLBS RO , 10$ 

Check for success 



CMPL RO , #LIB$_INPSTRTRU 

Error: Was it 
truncated string? 



BEQL 10$ 

PUSHL RO 

CALLS #1 . G*LIB$SIGNAL 

No, more serious error 

10$: 


MOVL #SS$_N0RMAL . RO 

; Success, or name too 
; long 



RET 

.END START 



Function Return Values in MACRO 

Function values are generally returned in RO (32-bit values) or R0:R1 
(64-bit) values. A MACRO program can access a function value by 
referencing RO or R0:R1 directly. For functions that return a string, the 
address of the string or the address of its descriptor is returned in RO. If a 
function needs to return a value larger than 64 bits, it must return the value 
by using an output argument. 

There are some exceptions to these rules: 

• JSB entry points in the MTH$ facility return H-floating values in R0:R3. 
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• One routine, MTH$SINCOS, returns two function values, the sine and 
the cosine of an angle. Depending on the data type of the function 
values, the function values are returned in the following registers: 

F-floating RO through R1 

D-floating or G-floating RO through R3 

H-floating RO through R7 

As in the case of output arguments, a variable declared to receive the function 

values must be exactly the same length as the value. 


3.10 Calling a Library Routine in BLISS 

This section describes how to code BLISS calls to library routines. A called 

routine can return only one of the following: 

• No value. 

• A function value (typically, an integer or floating-point number). For 
example, MTH$SIN returns its result as an F-floating value in RO. 

• A return status (typically, a 32-bit condition value) indicating that the 
routine has either executed successfully or failed. For example, 
LIB$GET_JNPUT returns a return status in RO. If the routine executed 
successfully, it returns SS$_NORMAL; if not, it returns one of several 
possible error condition values. BLISS treats the return status like any 
other value. 


3.10.1 BLISS Calling Sequence 

Scalar arguments are usually passed to Run-Time Library routines by 
reference. Thus, when a BLISS program passes a variable, it appears with 
no preceding period in the procedure-call actual argument list. A constant 
value can be easily passed using the %REF built-in function. 

The following example shows how a BLISS program calls 
LIB$PUT_OUTPUT. This routine writes a record at the user's terminal. 

MODULE SHOWTIME(IDENT=’ 1-1 ’ ‘/.TITLE’Print time’, MAIN=TIMEOUT) = 

BEGIN 

LIBRARY ’SYSSLIBRARY:STARLET’; ! Defines system services, etc. 

MACRO 

DESC[]=*/.CHARCOUNT (‘/.REMAINING), ! VAX string descriptor 
UPLIT BYTEC/.REMAINING) */,; ! definition 

BIND 

FMTDESC=UPLIT( DESCC’At the tone, the time will be ’, 

‘/.CHAR(7), ’!‘/,T’ )); 

EXTERNAL ROUTINE 

LIB$PUT_OUTPUT: ADDRESSING.MODE(GENERAL); 
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ROUTINE TIMEOUT 

BEGIN 
LOCAL 

TIMEBUF: VECTOR [2]. 

MSGBUF: VECTOR[80,BYTE], 

MSGDESC: BLOCK[8.BYTE]. 

RSLT: WORD; 


! 64-bit system time 
! Output message buffer 
! Descriptor for message buffer 
! Length of result string 


t + 

! Initialize the fields of the string descriptor. 

MSGDESC[DSC$B_CLASS]=DSC$K_CLASS_S; 
MSGDESC[DSC$B_DTYPE]=DSC$K_DTYPE_T; 
MSGDESC[DSC$W_LENGTH]=80; 

MSGDESC[DSC$A_POINTER]=MSGBUF[0] 

SGETTIM(TIMADR=TIMEBUF); ! 

$FAOL(CTRSTR=FMTDESC, ! 

OUTLEN=RSLT. ! 

OUTBUF=MSGDESC, 

PRMLST= ‘/.REF (TIMEBUF)); 

MSGDESC [DSC$W_LENGTH] = .RSLT; 

RETURN (LIB$PUT_OUTPUT(MSGDESC); 

END; 

END 

ELUDOM 


3.10.2 Accessing a Return Status in BLISS 

BLISS accesses a function return value or condition value returned in RO as 
follows: 

STATUS = LIB$PUT_OUTPUT(MSG_DESC); 

IF NOT .STATUS THEN LIB$STOP(.STATUS); 


3.10.3 Calling JSB Entry Points from BLISS 

Many of the library mathematics routines have JSB entry points. You can 
efficiently invoke these routines from a BLISS procedure using LINKAGE and 
EXTERNAL ROUTINE declarations as in the following example. 

MODULE JSB.LINK (MAIN = MATH.JSB, ! Example of using JSB linkage 

IDENT = * 1-001’, 

ADDRESSING.MODE(EXTERNAL = GENERAL)) = 

BEGIN 

LINKAGE 

LINK_MATH_R4 = JSB (REGISTER =0; ! input reg 

REGISTER = 0): ! output reg 
NOPRESERVE (0,1,2,3,4) 

NOTUSED (5,6,7,8,9,10,11); 

EXTERNAL ROUTINE 

MTH$SIND_R4 : LINK_MATH_R4; 

FORWARD ROUTINE 
MATH.JSB; 


Get time as 64-bit integer 

Format descriptor 
Output length (only a word!) 
! Output buffer desc. 
! Address of 64-bit 
! time block 
! Modify output desc. 
! Return status 
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LIBRARY ’SYS$LIBRARY:STARLET.L32’; 
ROUTINE MATH.JSB = 


! Routine 


BEGIN 

LOCAL 

INPUT.VALUE : INITIAL C/.E’30.0’), 

SIN.VALUE; 

! + 

! Get the sine of single floating 30 degrees. The input, 30 degrees, 
! is passed in RO, and the answer, is returned in RO. Registers 
! 0 to 4 are modified by MTH$SIND_R4. 


MTH$SIND_R4 (.INPUT.VALUE ; SIN.VALUE); 


RETURN SS$_N0RMAL; 
END; 


! End of routine 



END 

ELUDOM 


! End of module JSB.LINK 





3-22 






Index 


A 


LIB$GET_INPUT • 3-3 
LIB$SHOW_TIMER • 3-2 
LIB$SIGNAL*3-1 


Argument 

characteristics of*3-3, 3-6 
passing mechanism • 2-21 
VMS usage *2-6 


M 

MTH$SIN_R4 • 3-5 



Calling standard* 1-1, 3-1 
Condition value *3-6, 3-15 


D 


Descriptor 

class and data type *3-10 
fields of • 3-8 


E 


Entry point*3-4 

CALL entry point *3-3 
JSB entry point *3-5 
Error *3-15 

returning condition value *3-15 
signaling condition value *3-15 


F 


Function 

definition of • 1-1 
Function return value *3-6 



Passing mechanism • 2-24 
by descriptor *3-8 
by reference • 3-7 
by value *3-7 
for arrays *3-10 
for scalars • 3-9 
for strings *3-10 



Routine 

See also Entry point 
See also Mathematics routine 
definition of • 1-1 
how to call* 1-19, 3-1, 3-2 
Run-Time Library 
capabilities of • 1-1 
described* 1-1 
organization of* 1-19 
Run-Time Library routine 
capabilities of* 1-18 
defined* 1-1 

entry point *3-3, 3-4, 3-5 
how to call* 1-19, 3-1, 3-2 
linking with* 1-19 


L S_ 

LIB$FLT_UNDER *3-7 Shareable image *1-19 


Index-1 






























Index 



User procedure*3-1 



VAX BLISS 

using JSB entry point • 2-2 
VAX MACRO 

using JSB entry point *2-2 
VMS usage *2-6 


Index-2 










Reader's Comments 


Introduction to the VMS 
Run-Time Library 
AA-LA70A-TE 


Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 

I rate this manual's: 

Accuracy (software works as manual says) 
Completeness (enough information) 

Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 

I would like to see more/less _ 


Excellent 

Good 

Fair 

Poor 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 


What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 
Page Description 


Additional comments or suggestions to improve this manual: 


I am using Version _ of the software this manual describes. 


Name/Title _ 

Company _ 

Mailing Address 


Dept. _ 

_ Date 


Phone 








































Do Not Tear - Fold Here and Tape 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 33 MAYNARD MASS. 


POSTAGE WILL BE PAID BY ADDRESSEE 


DIGITAL EQUIPMENT CORPORATION 
Corporate User Publications—Spit Brook 
ZK01-3/J35 110 SPIT BROOK ROAD 
NASHUA, NH 03062-9987 


No Postage 
Necessary 
if Mailed 
in the 

United States 







Do Not Tear - Fold Here 


















Reader's Comments 


Introduction to the VMS 
Run-Time Library 
AA-LA70A-TE 


“ZS " y °V'***' * “P*y “ » *> ft w„e 

comments on an SPR form. S ° ftWare Performa nce Report (SPR) service" submit your 

Thank you for your assistance. 


I rate this manual's: 

Accuracy (software works as manual says) 
Completeness (enough information) 

Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 


Excellent Good Fair 

n □ □ 

□ □ □ 

□ □ □ 

□ □ □ 

□ □ □ 

□ □ □ 

D □ □ 

□ □ □ 


Poor 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 


I would like to see more/less 




I found the following errors in this manual: 
Page Description 



Additional comments or suggestions to improve this manual: 



Name/Title _ 

Company _ 

Mailing Address 


Dept. __ 

-- Date 


Phone 



































































_Do Not Tear - Fold Here and Tape 


I 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 33 MAYNARD MASS. 
POSTAGE WILL BE PAID BY ADDRESSEE 


DIGITAL EQUIPMENT CORPORATION 
Corporate User Publications—Spit Brook 
ZK01-3/J35 110 SPIT BROOK ROAD 
NASHUA, NH 03062-9987 


No Postage 
Necessary 
if Mailed | 


in the 

United States I 



« 


Do Not Tear - Fold Here 



I 

I 

I 

I 

I 


I 


I 


Cut Along Dotted Line 























